create-windy 0.6.12 → 0.6.14

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

@@ -1,20 +1,15 @@
 import type { ModuleManifest } from "@southwind-ai/modules";
-import {
-  resolveProviderEgress,
-  resolveToolNetworkPolicy,
-} from "@southwind-ai/modules";
+import { resolveToolNetworkPolicy } from "@southwind-ai/modules";
 import type {
   ModuleAiArtifactRef,
   ModuleAiJsonValue,
 } from "@southwind-ai/server-sdk";
-import { evaluateAccessGuards } from "../access-guards.js";
+import type { AgentWorkflowBudget } from "@southwind-ai/shared";
 import 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 type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import {
-  AgentRunAuthorizationError,
   type AgentExecutionAuthorization,
   type AgentRunAuthorizationStore,
 } from "./run-authorization.js";
@@ -23,11 +18,6 @@ import type {
   AgentRuntimeStartResponse,
 } from "./run-contracts.js";
 import { AgentRuntimeError } from "./run-contracts.js";
-import {
-  governProviderInput,
-  projectProviderInput,
-  ProviderInputGovernanceError,
-} from "./provider-input-governance.js";
 import {
   rotateVisionArtifacts,
   validateVisionArtifacts,
@@ -41,27 +31,45 @@ import {
 import type { ScreenshotIntakeRuntimeV2 } from "./screenshot-intake-v2.js";
 import { attachAgentRun } from "./run-attach.js";
 import {
-  assertInputSize,
   digest,
   publicRunPath,
   runtimeErrorStatus,
 } from "./run-definition-support.js";
-import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
+import { AgentRunFacadeError } from "./run-errors.js";
 import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
 import { verifyCommittedRunInput } from "./run-input-verification.js";
-import { assertSelectedDebugOperation } from "./run-debug-authorization.js";
 import {
   buildRegisteredOperations,
   type RegisteredOperation,
 } from "./run-operation-registry.js";
-import { validateRegisteredOutputSchema } from "./run-output-schema.js";
+import type { AgentRunSessionLinkPort } from "./session-run-link.js";
+import {
+  beginSessionTurn,
+  linkSessionTurn,
+  type PendingSessionTurn,
+} from "./session-run-lifecycle.js";
+import { cleanupFailedAgentRun } from "./run-failure-cleanup.js";
+import { buildAgentRuntimeRequest } from "./run-runtime-request.js";
+import { prepareAgentRunStart } from "./run-start-preparation.js";
+import {
+  authorizeAgentRunBrowser,
+  authorizeAgentRunMutation,
+} from "./run-browser-authorization.js";
+import {
+  AgentRunSessionBindingAuthorizer,
+  authorizeAgentRunStart,
+} from "./run-session-authorization.js";
+import {
+  resolveAgentRunExecutionPolicy,
+  type AgentRunDelegationPolicy,
+} from "./agent-run-delegation-policy.js";
+import { publicAgentOperationPolicy } from "./run-operation-policy.js";
 export { AgentRunFacadeError } from "./run-errors.js";
-
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
-
 export class AgentRunFacade {
   readonly #operations: Map<string, RegisteredOperation>;
   readonly #modules: readonly ModuleManifest[];
+  readonly #sessionBindingAuthorization: AgentRunSessionBindingAuthorizer;
   constructor(
     modules: readonly ModuleManifest[],
     hosts: InitializedModuleHosts,
@@ -70,9 +78,18 @@ export class AgentRunFacade {
     private readonly authorizations: AgentRunAuthorizationStore,
     private readonly artifacts?: AiArtifactRuntime,
     private readonly screenshots?: ScreenshotIntakeRuntimeV2,
+    private readonly sessionLinks?: AgentRunSessionLinkPort,
   ) {
     this.#modules = modules;
     this.#operations = buildRegisteredOperations(modules, hosts);
+    this.#sessionBindingAuthorization = new AgentRunSessionBindingAuthorizer(
+      modules,
+      runtime,
+    );
+  }
+
+  operationPolicy(operationKey: string) {
+    return publicAgentOperationPolicy(this.#operations.get(operationKey));
   }
   async start(
     operationKey: string,
@@ -82,13 +99,11 @@ export class AgentRunFacade {
     artifacts: readonly ModuleAiArtifactRef[] = [],
     signal: AbortSignal = AbortSignal.timeout(10_000),
     screenshotIntakeToken?: string,
+    sessionId?: string,
+    delegationPolicy?: AgentRunDelegationPolicy,
+    runtimeBudget?: AgentWorkflowBudget,
+    modelPin?: { readonly deploymentKey: string; readonly model: string },
   ): Promise<AgentRuntimeStartResponse> {
-    assertSelectedDebugOperation(
-      this.runtime,
-      context.actor.id,
-      operationKey,
-      "forbidden",
-    );
     const operation = this.#operations.get(operationKey);
     if (
       !operation?.registration?.prepare ||
@@ -101,63 +116,23 @@ export class AgentRunFacade {
         404,
       );
     }
-    const decision = await evaluateAccessGuards(this.runtime, context, {
-      permission: {
-        permissionKey: operation.definition.permissionKey,
-      },
-      feature: operation.feature,
-    });
-    if (!decision.decision.allowed) {
-      throw new AgentRunFacadeError(
-        "FORBIDDEN",
-        "无权执行 Agent Operation",
-        403,
-      );
-    }
-    assertInputSize(input, operation.definition.limits.maxInputBytes);
-    const providerPolicy = operation.definition.providerDataPolicy;
-    if (
-      operation.definition.providerEgress?.mode === "configured-endpoint" &&
-      !providerPolicy
-    ) {
-      throw new AgentRunFacadeError(
-        "FORBIDDEN",
-        "Agent Operation 缺少 Provider 字段治理策略",
-        403,
-      );
-    }
-    let governedInput = input;
-    let committedInput = input;
-    try {
-      committedInput = providerPolicy
-        ? projectProviderInput(input, providerPolicy)
-        : input;
-      governedInput = providerPolicy
-        ? governProviderInput(input, providerPolicy)
-        : input;
-    } catch (error) {
-      if (error instanceof ProviderInputGovernanceError) {
-        throw new AgentRunFacadeError(
-          error.code,
-          error.message,
-          error.code === "FORBIDDEN" ? 403 : 400,
-        );
-      }
-      throw error;
-    }
-    const moduleActor = toModuleActor(context.actor);
-    const plan = await operation.registration.prepare(governedInput, {
-      actor: moduleActor,
-      requestId: context.requestId,
+    await authorizeAgentRunStart({
+      runtime: this.runtime,
+      operation,
+      context,
+      ...(sessionId
+        ? { sessionBinding: this.#sessionBindingAuthorization }
+        : {}),
     });
-    if (!plan.instructions.trim() || !plan.userPrompt.trim()) {
-      throw new AgentRunFacadeError(
-        "INVALID_INPUT",
-        "Agent Operation 执行计划无效",
-        400,
-      );
-    }
-    validateRegisteredOutputSchema(plan.outputSchema, operation);
+    const executionPolicy = resolveAgentRunExecutionPolicy(
+      operation,
+      context,
+      delegationPolicy,
+      runtimeBudget,
+      modelPin,
+    );
+    const { committedInput, currentCaseId, governedInput, moduleActor, plan } =
+      await prepareAgentRunStart(operation, input, context);
     const rotatedArtifacts = await rotateVisionArtifacts(
       artifacts,
       operation.definition,
@@ -174,17 +149,30 @@ export class AgentRunFacade {
     let authorization: AgentExecutionAuthorization | undefined;
     let screenshot: ScreenshotRunBinding | undefined;
     let created: AgentRuntimeStartResponse | undefined;
+    let sessionTurn: PendingSessionTurn | undefined;
+    let sessionLinked = false;
     try {
       authorization = await this.authorizations.issue({
         operationKey,
         releaseId: release.releaseId,
         idempotencyKey,
+        ...(sessionId ? { sessionId } : {}),
         input: committedInput,
         authorizationSnapshot: {
           permissionKey: operation.definition.permissionKey,
           featureKey: operation.definition.featureKey,
-          allowedToolKeys: [...operation.definition.allowedToolKeys],
+          allowedToolKeys: [...executionPolicy.allowedToolKeys],
           toolNetworkMode: resolveToolNetworkPolicy(operation.definition).mode,
+          ...(executionPolicy.authorizationDelegation
+            ? { delegation: executionPolicy.authorizationDelegation }
+            : {}),
+          ...(executionPolicy.budgetDigest
+            ? { runtimeBudgetDigest: executionPolicy.budgetDigest }
+            : {}),
+          ...(executionPolicy.modelPin
+            ? { modelPin: structuredClone(executionPolicy.modelPin) }
+            : {}),
+          ...(currentCaseId ? { memoryScopeCaseId: currentCaseId } : {}),
         },
         context,
       });
@@ -210,47 +198,46 @@ export class AgentRunFacade {
         ? [...rotatedArtifacts, screenshot.artifact]
         : rotatedArtifacts;
       validateVisionArtifacts(runtimeArtifacts, operation.definition);
+      sessionTurn = await beginSessionTurn(this.sessionLinks, {
+        ...(sessionId ? { sessionId } : {}),
+        ...(authorization.binding.runId
+          ? { existingRunId: authorization.binding.runId }
+          : {}),
+        operationKey,
+        recoveryKey: authorization.binding.bindingId,
+        committedInput,
+        ...(currentCaseId ? { currentCaseId } : {}),
+        context,
+      });
       created = await this.remote.start(
-        {
-          kind: "agent",
+        buildAgentRuntimeRequest({
           operationKey,
           input: governedInput,
-          inputModalities: operation.definition.inputModalities ?? ["text"],
-          requiredCapabilities: operation.definition.requiredCapabilities,
+          operation,
+          plan,
           artifacts: runtimeArtifacts,
-          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),
-          providerDataPolicy: operation.definition.providerDataPolicy ?? {
-            inputFields: [],
-            envelopeFields: [],
-          },
-          toolNetworkPolicy: resolveToolNetworkPolicy(operation.definition),
-          ...(readinessPin === undefined ? {} : { readinessPin }),
-          executionGrant: authorization.token,
+          readinessPin,
+          authorizationToken: authorization.token,
           release,
           traceId,
-          reporting: {
-            actorId: moduleActor.id,
-            actorType: moduleActor.type,
-            ...(context.actor.scopeContext?.departmentId
-              ? { departmentId: context.actor.scopeContext.departmentId }
-              : {}),
-          },
-        },
+          actor: moduleActor,
+          departmentId: context.actor.scopeContext?.departmentId,
+          sessionTurn,
+          executionPolicy,
+        }),
         scopedRuntimeIdempotencyKey(
           context.actor.id,
           operationKey,
           idempotencyKey,
+          sessionId,
         ),
       );
       await this.authorizations.bind(authorization, created.runId);
+      sessionLinked = await linkSessionTurn(
+        this.sessionLinks,
+        sessionTurn,
+        created.runId,
+      );
       await screenshot?.bind(created.runId);
       auditAgentRun({
         runtime: this.runtime,
@@ -267,9 +254,17 @@ export class AgentRunFacade {
         eventsUrl: publicRunPath(created.runId, "events", operationKey),
       };
     } catch (error) {
-      if (created && screenshot) await this.remote.cancel(created.runId);
-      if (authorization) await this.authorizations.discard(authorization);
-      if (screenshot) await screenshot.cancel();
+      await cleanupFailedAgentRun({
+        cause: error,
+        remote: this.remote,
+        authorizations: this.authorizations,
+        sessionLinks: this.sessionLinks,
+        created,
+        authorization,
+        screenshot,
+        sessionTurn,
+        sessionLinked,
+      });
       if (error instanceof AgentRuntimeError) {
         throw new AgentRunFacadeError(
           error.code,
@@ -280,45 +275,49 @@ export class AgentRunFacade {
       throw error;
     }
   }
-
   async authorizeRun(
     operationKey: string,
     runId: string,
     context: RequestGuardContext,
   ) {
-    assertSelectedDebugOperation(
-      this.runtime,
-      context.actor.id,
+    const authorized = await authorizeAgentRunBrowser({
+      operations: this.#operations,
+      authorizations: this.authorizations,
+      runtime: this.runtime,
       operationKey,
-      "hidden",
-    );
-    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,
+      runId,
+      context,
+    });
+    return {
+      operation: authorized.operation,
+      sessionId: authorized.binding.sessionId,
+    };
+  }
+  async authorizeRunMutation(
+    operationKey: string,
+    runId: string,
+    context: RequestGuardContext,
+    sessionId?: string,
+  ) {
+    return authorizeAgentRunMutation({
+      operations: this.#operations,
+      authorizations: this.authorizations,
+      runtime: this.runtime,
+      operationKey,
+      runId,
+      context,
+      ...(sessionId ? { requestedSessionId: sessionId } : {}),
+      sessionAuthorizer: this.#sessionBindingAuthorization,
+      sessionLinks: this.sessionLinks,
     });
-    if (!decision.decision.allowed) throw inaccessibleRun();
-    return operation;
   }
-
   async verifyRunInput(
     operationKey: string,
     runId: string,
     input: ModuleAiJsonValue,
     context: RequestGuardContext,
   ): Promise<void> {
-    const operation = await this.authorizeRun(operationKey, runId, context);
+    const { operation } = await this.authorizeRun(operationKey, runId, context);
     await verifyCommittedRunInput({
       operationKey,
       runId,
@@ -328,13 +327,13 @@ export class AgentRunFacade {
       authorizations: this.authorizations,
     });
   }
-
   async attach(
     operationKey: string,
     runId: string,
     cursor: number,
     context: RequestGuardContext,
     signal?: AbortSignal,
+    sessionId?: string,
   ) {
     return attachAgentRun({
       operationKey,
@@ -343,7 +342,8 @@ export class AgentRunFacade {
       context,
       signal,
       remote: this.remote,
-      authorize: () => this.authorizeRun(operationKey, runId, context),
+      authorize: () =>
+        this.authorizeRunMutation(operationKey, runId, context, sessionId),
     });
   }
 }

package/template/apps/server/src/agent/run-failure-cleanup.ts

@@ -0,0 +1,58 @@
+import type {
+  AgentExecutionAuthorization,
+  AgentRunAuthorizationStore,
+} from "./run-authorization.js";
+import type {
+  AgentRuntimePort,
+  AgentRuntimeStartResponse,
+} from "./run-contracts.js";
+import type { ScreenshotRunBinding } from "./screenshot-run-binding.js";
+import { failSessionTurn, type PendingSessionTurn } from "./session-run-lifecycle.js";
+import type { AgentRunSessionLinkPort } from "./session-run-link.js";
+
+export async function cleanupFailedAgentRun(input: {
+  readonly cause: unknown;
+  readonly remote: AgentRuntimePort;
+  readonly authorizations: AgentRunAuthorizationStore;
+  readonly sessionLinks: AgentRunSessionLinkPort | undefined;
+  readonly created: AgentRuntimeStartResponse | undefined;
+  readonly authorization: AgentExecutionAuthorization | undefined;
+  readonly screenshot: ScreenshotRunBinding | undefined;
+  readonly sessionTurn: PendingSessionTurn | undefined;
+  readonly sessionLinked: boolean;
+}) {
+  const failures: unknown[] = [];
+  await capture(failures, () =>
+    input.created ? input.remote.cancel(input.created.runId) : undefined,
+  );
+  await capture(failures, () =>
+    input.authorization
+      ? input.authorizations.discard(input.authorization)
+      : undefined,
+  );
+  await capture(failures, () => input.screenshot?.cancel());
+  await capture(failures, () =>
+    failSessionTurn(
+      input.sessionLinks,
+      input.sessionTurn,
+      input.sessionLinked,
+    ),
+  );
+  if (failures.length) {
+    throw new AggregateError(
+      [input.cause, ...failures],
+      "Agent Run 失败且清理或 Session Turn 补偿未收敛",
+    );
+  }
+}
+
+async function capture(
+  failures: unknown[],
+  action: () => Promise<unknown> | undefined,
+) {
+  try {
+    await action();
+  } catch (error) {
+    failures.push(error);
+  }
+}

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

@@ -0,0 +1,20 @@
+import { resolveProviderEgress } from "@southwind-ai/modules";
+import type { RegisteredOperation } from "./run-operation-registry.js";
+
+export function publicAgentOperationPolicy(
+  operation: RegisteredOperation | undefined,
+) {
+  if (operation?.definition.kind !== "agent") return undefined;
+  const provider = resolveProviderEgress(operation.definition);
+  return {
+    requiredCapabilities: [...operation.definition.requiredCapabilities],
+    allowedToolKeys: [...operation.definition.allowedToolKeys],
+    featureKey: operation.definition.featureKey,
+    permissionKey: operation.definition.permissionKey,
+    deploymentKey:
+      provider.mode === "configured-endpoint"
+        ? provider.deploymentKey
+        : undefined,
+    release: structuredClone(operation.release),
+  };
+}

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

@@ -7,16 +7,22 @@ import { AgentRunFacadeError } from "./run-errors.js";
 export function parseAttachRequest(body: unknown): {
   operationKey: string;
   cursor: number;
+  sessionId?: string;
 } {
   if (
     !isRecord(body) ||
-    Object.keys(body).some((key) => !["operationKey", "cursor"].includes(key))
+    Object.keys(body).some((key) =>
+      !["operationKey", "cursor", "sessionId"].includes(key),
+    )
   ) {
     throw new AgentRunFacadeError("INVALID_INPUT", "请求格式无效", 400);
   }
   return {
     operationKey: parseOperationKey(body.operationKey),
     cursor: parseCursorValue(body.cursor),
+    ...(body.sessionId === undefined
+      ? {}
+      : { sessionId: parseSessionId(body.sessionId) }),
   };
 }
 
@@ -36,6 +42,7 @@ export function parseStartRequest(body: unknown): {
   input: ModuleAiJsonValue;
   artifacts: readonly ModuleAiArtifactRef[];
   screenshotIntakeToken?: string;
+  sessionId?: string;
 } {
   if (
     !isRecord(body) ||
@@ -46,6 +53,7 @@ export function parseStartRequest(body: unknown): {
           "input",
           "artifacts",
           "screenshotIntakeToken",
+          "sessionId",
         ].includes(key),
     )
   ) {
@@ -64,9 +72,19 @@ export function parseStartRequest(body: unknown): {
             body.screenshotIntakeToken,
           ),
         }),
+    ...(body.sessionId === undefined
+      ? {}
+      : { sessionId: parseSessionId(body.sessionId) }),
   };
 }
 
+export function parseSessionId(value: unknown): string {
+  if (typeof value !== "string" || !/^session_[A-Za-z0-9-]{1,72}$/.test(value)) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "Session ID 无效", 400);
+  }
+  return value;
+}
+
 function parseScreenshotToken(value: unknown): string {
   if (typeof value !== "string" || !/^[0-9a-f-]{36}$/i.test(value)) {
     throw new AgentRunFacadeError(