create-windy 0.6.14 → 0.6.15

package/template/apps/server/src/agent/client-workflow-artifact/workflow-loader.ts

@@ -0,0 +1,285 @@
+import type { AgentWorkflowNode } from "@southwind-ai/shared";
+import { CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX } from "@southwind-ai/server-sdk";
+import type { DurableJobService } from "../../jobs/service.js";
+import { hashAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import { digestJson } from "../client-session/digest.js";
+import { DrizzleAgentWorkflowRepository } from "../../agent-workflow/drizzle-repository.js";
+import { ReceiptAgentWorkflowNodeInputPort } from "../../agent-workflow/node-input-receipt-port.js";
+import { schedulerAdapterContext } from "../../agent-workflow/scheduler-context.js";
+import {
+  clientWorkflowBindingCommitment,
+  ClientAgentWorkflowArtifactBindingRegistry,
+} from "./binding-registry.js";
+import { assertClientAgentWorkflowReleaseBinding } from "./release-binding.js";
+import {
+  clientAgentWorkflowArtifactTaskKey,
+  type ClientAgentWorkflowBeginFacts,
+} from "./contracts.js";
+import { requireClientWorkflowFrozenScope } from "./scope-authority.js";
+
+export interface ClientAgentWorkflowJobPayload {
+  readonly commandId: string;
+  readonly runId: string;
+  readonly nodeRunId: string;
+  readonly effectGeneration?: number;
+  readonly requestDigest?: string;
+}
+
+type WorkflowSnapshot = NonNullable<
+  Awaited<ReturnType<DrizzleAgentWorkflowRepository["getSnapshot"]>>
+>;
+
+export class ClientAgentWorkflowFactsLoader {
+  readonly #inputs = new ReceiptAgentWorkflowNodeInputPort();
+
+  constructor(
+    private readonly workflows: DrizzleAgentWorkflowRepository,
+    private readonly jobs: DurableJobService,
+    private readonly bindings: ClientAgentWorkflowArtifactBindingRegistry,
+  ) {}
+
+  async load(input: {
+    jobId: string;
+    payload: ClientAgentWorkflowJobPayload;
+    signal: AbortSignal;
+  }): Promise<ClientAgentWorkflowBeginFacts> {
+    const [snapshot, job] = await Promise.all([
+      this.workflows.getSnapshot(input.payload.runId),
+      this.jobs.get(input.jobId),
+    ]);
+    if (!snapshot || !job) throw invalid("WORKFLOW_FACTS_NOT_FOUND");
+    const release = await this.workflows.getRelease(snapshot.run.releaseId);
+    const nodeRun = snapshot.nodeRuns.find(
+      ({ nodeRunId }) => nodeRunId === input.payload.nodeRunId,
+    );
+    const command = snapshot.sideEffects.find(
+      ({ commandId }) => commandId === input.payload.commandId,
+    );
+    const node = release?.definition.nodes.find(
+      ({ id }) => id === nodeRun?.nodeId,
+    );
+    if (!release || !nodeRun || !command || !node) {
+      throw invalid("WORKFLOW_COORDINATE_NOT_FOUND");
+    }
+    assertJobAndFence({ input, snapshot, job, nodeRun, command, node });
+    const binding = this.bindings.require(
+      release.definition.workflowKey,
+      node.id,
+    );
+    assertClientAgentWorkflowReleaseBinding(release, binding);
+    const context = schedulerAdapterContext({
+      snapshot,
+      release,
+      nodeRun,
+      node,
+      signal: input.signal,
+    });
+    const value = await this.#inputs.readJson({
+      context,
+      ...(node.inputSchemaKey ? { schemaKey: node.inputSchemaKey } : {}),
+    });
+    const record: ClientAgentWorkflowBeginFacts["record"] = {
+      workId: workflowWorkId(command.commandId),
+      commandId: command.commandId,
+      durableJobId: input.jobId,
+      runId: snapshot.run.runId,
+      nodeRunId: nodeRun.nodeRunId,
+      effectKind: "job",
+      taskKey: clientAgentWorkflowArtifactTaskKey,
+      operationKey: binding.operationKey,
+      bindingDigest: digestJson(clientWorkflowBindingCommitment(binding)),
+      actorId: snapshot.run.actorId,
+      scopeDigest: requireDigest(snapshot.run.scopeDigest),
+      authorizationSnapshotDigest: requireDigest(
+        command.authorizationSnapshotDigest,
+      ),
+      runPolicyDigest: requireDigest(command.runPolicyDigest),
+      requestDigest: requireDigest(command.requestDigest),
+      inputDigest: digestJson(value),
+      effectGeneration: command.generation,
+      effectFenceTokenDigest: requireDigest(command.fenceTokenDigest),
+      status: "pending",
+      claimGeneration: 0,
+      historySequence: 0,
+      version: 1,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    return {
+      input: value,
+      inputArtifacts: context.inputArtifacts,
+      binding,
+      frozenScope: requireClientWorkflowFrozenScope(record, job),
+      record,
+    };
+  }
+
+  async loadTerminal(input: {
+    record: ClientAgentWorkflowBeginFacts["record"];
+    signal: AbortSignal;
+  }): Promise<
+    Pick<
+      ClientAgentWorkflowBeginFacts,
+      "binding" | "input" | "inputArtifacts" | "frozenScope"
+    >
+  > {
+    const [snapshot, job] = await Promise.all([
+      this.workflows.getSnapshot(input.record.runId),
+      this.jobs.get(input.record.durableJobId),
+    ]);
+    if (!snapshot || !job) throw invalid("WORKFLOW_FACTS_NOT_FOUND");
+    const release = await this.workflows.getRelease(snapshot.run.releaseId);
+    const nodeRun = snapshot.nodeRuns.find(
+      ({ nodeRunId }) => nodeRunId === input.record.nodeRunId,
+    );
+    const command = snapshot.sideEffects.find(
+      ({ commandId }) => commandId === input.record.commandId,
+    );
+    const node = release?.definition.nodes.find(
+      ({ id }) => id === nodeRun?.nodeId,
+    );
+    if (!release || !nodeRun || !command || !node) {
+      throw invalid("WORKFLOW_COORDINATE_NOT_FOUND");
+    }
+    const binding = this.bindings.require(
+      release.definition.workflowKey,
+      node.id,
+    );
+    assertClientAgentWorkflowReleaseBinding(release, binding);
+    const context = schedulerAdapterContext({
+      snapshot,
+      release,
+      nodeRun,
+      node,
+      signal: input.signal,
+    });
+    const value = await this.#inputs.readJson({
+      context,
+      ...(node.inputSchemaKey ? { schemaKey: node.inputSchemaKey } : {}),
+    });
+    assertTerminalIdentity({
+      record: input.record,
+      snapshot,
+      release,
+      nodeRun,
+      command,
+      node,
+      binding,
+      inputDigest: digestJson(value),
+    });
+    return {
+      binding,
+      input: value,
+      inputArtifacts: context.inputArtifacts,
+      frozenScope: requireClientWorkflowFrozenScope(input.record, job),
+    };
+  }
+}
+
+function assertJobAndFence(input: {
+  input: {
+    jobId: string;
+    payload: ClientAgentWorkflowJobPayload;
+  };
+  snapshot: WorkflowSnapshot;
+  job: NonNullable<Awaited<ReturnType<DurableJobService["get"]>>>;
+  nodeRun: WorkflowSnapshot["nodeRuns"][number];
+  command: WorkflowSnapshot["sideEffects"][number];
+  node: AgentWorkflowNode;
+}) {
+  const { payload } = input.input;
+  const { job } = input.job;
+  if (
+    job.id !== input.input.jobId ||
+    job.handlerKey !== clientAgentWorkflowArtifactTaskKey ||
+    job.requestedBy !== input.snapshot.run.actorId ||
+    !job.authorizationScope ||
+    `sha256:${hashAuthorizationScope(job.authorizationScope)}` !==
+      input.snapshot.run.scopeDigest ||
+    input.node.type !== "job" ||
+    input.node.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    input.nodeRun.nodeType !== "job" ||
+    input.nodeRun.runId !== input.snapshot.run.runId ||
+    input.command.runId !== input.snapshot.run.runId ||
+    input.command.nodeRunId !== input.nodeRun.nodeRunId ||
+    input.command.effectKind !== "job" ||
+    input.command.status !== "dispatched" ||
+    input.command.generation < 1 ||
+    !input.command.fenceTokenDigest ||
+    input.command.authorizationSnapshotDigest !==
+      input.snapshot.run.authorizationSnapshotDigest ||
+    input.command.runPolicyDigest !==
+      input.snapshot.run.executionPolicyDigest ||
+    (payload.effectGeneration !== undefined &&
+      payload.effectGeneration !== input.command.generation) ||
+    (payload.requestDigest !== undefined &&
+      payload.requestDigest !== input.command.requestDigest)
+  ) {
+    throw invalid("WORKFLOW_EFFECT_FENCE_INVALID");
+  }
+}
+
+function assertTerminalIdentity(input: {
+  record: ClientAgentWorkflowBeginFacts["record"];
+  snapshot: WorkflowSnapshot;
+  release: NonNullable<
+    Awaited<ReturnType<DrizzleAgentWorkflowRepository["getRelease"]>>
+  >;
+  nodeRun: WorkflowSnapshot["nodeRuns"][number];
+  command: WorkflowSnapshot["sideEffects"][number];
+  node: AgentWorkflowNode;
+  binding: ClientAgentWorkflowBeginFacts["binding"];
+  inputDigest: `sha256:${string}`;
+}) {
+  const { record, snapshot, release, nodeRun, command, node, binding } = input;
+  if (
+    snapshot.run.releaseId !== release.releaseId ||
+    snapshot.run.runId !== record.runId ||
+    snapshot.run.actorId !== record.actorId ||
+    snapshot.run.scopeDigest !== record.scopeDigest ||
+    snapshot.run.authorizationSnapshotDigest !==
+      record.authorizationSnapshotDigest ||
+    snapshot.run.executionPolicyDigest !== record.runPolicyDigest ||
+    !["running", "waiting", "completed"].includes(snapshot.run.status) ||
+    nodeRun.nodeRunId !== record.nodeRunId ||
+    nodeRun.runId !== record.runId ||
+    nodeRun.nodeId !== binding.nodeId ||
+    nodeRun.nodeType !== "job" ||
+    !["running", "waiting", "completed"].includes(nodeRun.status) ||
+    node.type !== "job" ||
+    node.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    command.commandId !== record.commandId ||
+    command.runId !== record.runId ||
+    command.nodeRunId !== record.nodeRunId ||
+    command.effectKind !== record.effectKind ||
+    command.effectKey !== node.id ||
+    command.adapter.kind !== "durable-job" ||
+    !["dispatched", "committed", "reconciled"].includes(command.status) ||
+    command.generation !== record.effectGeneration ||
+    command.requestDigest !== record.requestDigest ||
+    command.fenceTokenDigest !== record.effectFenceTokenDigest ||
+    command.authorizationSnapshotDigest !==
+      record.authorizationSnapshotDigest ||
+    command.runPolicyDigest !== record.runPolicyDigest ||
+    record.taskKey !== clientAgentWorkflowArtifactTaskKey ||
+    record.operationKey !== binding.operationKey ||
+    record.bindingDigest !==
+      digestJson(clientWorkflowBindingCommitment(binding)) ||
+    record.inputDigest !== input.inputDigest
+  ) {
+    throw invalid("WORKFLOW_TERMINAL_IDENTITY_INVALID");
+  }
+}
+
+function workflowWorkId(commandId: string) {
+  return `${CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX}${digestJson({ commandId }).slice("sha256:".length, 53)}`;
+}
+
+function requireDigest(value: string | undefined): `sha256:${string}` {
+  if (!value?.startsWith("sha256:")) throw invalid("DIGEST_INVALID");
+  return value as `sha256:${string}`;
+}
+
+function invalid(code: string) {
+  return new Error(code);
+}

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

@@ -10,8 +10,9 @@ import { createTestRunAuthorizationStore } from "./run-authorization.test-suppor
 
 export async function createRunFacadeFixture(
   permissionKeys: string[] = ["business.ai.execute", "business.records.read"],
+  options: { workflowOnly?: boolean } = {},
 ) {
-  const module = runFacadeManifest();
+  const module = runFacadeManifest(options.workflowOnly);
   const prepared: unknown[] = [];
   const hosts = await initializeModuleHosts({
     modules: [module],
@@ -90,7 +91,7 @@ export function guardContext(permissionKeys: string[]) {
   );
 }
 
-export function runFacadeManifest(): ModuleManifest {
+export function runFacadeManifest(workflowOnly = false): ModuleManifest {
   return {
     name: "business",
     version: "0.1.0",
@@ -144,13 +145,13 @@ export function runFacadeManifest(): ModuleManifest {
         },
       },
     ],
-    aiOperations: [agentOperation()],
+    aiOperations: [agentOperation(workflowOnly)],
     providers: [],
     auditActions: ["business.ai.execute", "business.records.read"],
   };
 }
 
-function agentOperation() {
+function agentOperation(workflowOnly: boolean) {
   return {
     key: "business.answer",
     kind: "agent" as const,
@@ -187,6 +188,18 @@ function agentOperation() {
         },
       ],
     },
+    ...(workflowOnly
+      ? {
+          clientExecution: {
+            mode: "governed-session" as const,
+            launchAuthority: "workflow-artifact" as const,
+            maxSteps: 4,
+            maxRequestBytes: 4096,
+            maxResponseBytes: 4096,
+            maxConcurrentRequests: 1,
+          },
+        }
+      : {}),
     toolNetworkPolicy: { mode: "forbidden" as const },
     limits: {
       maxDurationSeconds: 60,

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

@@ -96,6 +96,22 @@ describe("Guarded Agent Run facade", () => {
     expect(fixture.prepared).toEqual([]);
   });
 
+  test("workflow-only Client Operation 不允许普通 Agent Run 直接启动", async () => {
+    const fixture = await createRunFacadeFixture(undefined, {
+      workflowOnly: true,
+    });
+    await expect(
+      fixture.facade.start(
+        "business.answer",
+        { question: "绕过 Workflow" },
+        "request-workflow-bypass",
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "OPERATION_NOT_FOUND", status: 404 });
+    expect(fixture.remote.started).toEqual([]);
+    expect(fixture.prepared).toEqual([]);
+  });
+
   test("恢复时权限已收回会返回不泄露 Run 存在性的 404", async () => {
     const fixture = await createRunFacadeFixture();
     await fixture.facade.start(

package/template/apps/server/src/agent/run-session-authorization.ts

@@ -41,11 +41,7 @@ export class AgentRunSessionBindingAuthorizer {
       feature: this.#feature,
     });
     if (!access.decision.allowed) {
-      throw new AgentRunFacadeError(
-        "FORBIDDEN",
-        "无权写入长期 Session",
-        403,
-      );
+      throw new AgentRunFacadeError("FORBIDDEN", "无权写入长期 Session", 403);
     }
   }
 }
@@ -56,6 +52,16 @@ export async function authorizeAgentRunStart(input: {
   readonly context: RequestGuardContext;
   readonly sessionBinding?: AgentRunSessionBindingAuthorizer;
 }): Promise<void> {
+  if (
+    input.operation.definition.clientExecution?.launchAuthority ===
+    "workflow-artifact"
+  ) {
+    throw new AgentRunFacadeError(
+      "OPERATION_NOT_FOUND",
+      "Agent Operation 不存在",
+      404,
+    );
+  }
   const decision = await evaluateAccessGuards(input.runtime, input.context, {
     permission: {
       permissionKey: input.operation.definition.permissionKey,
@@ -63,11 +69,7 @@ export async function authorizeAgentRunStart(input: {
     feature: input.operation.feature,
   });
   if (!decision.decision.allowed) {
-    throw new AgentRunFacadeError(
-      "FORBIDDEN",
-      "无权执行 Agent Operation",
-      403,
-    );
+    throw new AgentRunFacadeError("FORBIDDEN", "无权执行 Agent Operation", 403);
   }
   await input.sessionBinding?.requireManage(input.context);
 }

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

@@ -1,7 +1,10 @@
 import type { PlatformConfig } from "@southwind-ai/config";
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
 import type { ModuleManifest } from "@southwind-ai/modules";
-import type { ModuleClientAgentHostAuthAdapter } from "@southwind-ai/server-sdk";
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentWorkflowArtifactProjectBinding,
+} from "@southwind-ai/server-sdk";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { InitializedModuleHosts } from "../module-host.js";
 import type { createServerRuntime } from "../runtime.js";
@@ -36,6 +39,7 @@ export interface AgentPlatformRuntimeInput {
   backgroundAi: DeferredAgentBackgroundOperationPortFactory;
   screenshotPageRegistry?: ScreenshotPageRegistryV2;
   clientAgentHostAuth?: ModuleClientAgentHostAuthAdapter;
+  clientAgentWorkflowArtifactBindings?: readonly ModuleClientAgentWorkflowArtifactProjectBinding[];
   authoritativeSessionSources?: readonly ModuleAuthoritativeSourceAdapterRegistration[];
   sessionMemoryObjects?: readonly ModuleMemoryObjectAdapterRegistration[];
   agentWorkflowWorkspacePolicies?: readonly AgentWorkflowWorkspacePolicyDefinition[];

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

@@ -43,6 +43,8 @@ import { createModuleAiPorts } from "./module-ai-port-factory.js";
 import { createManifestAuthorizedRouteApp } from "../module-host/static-route-authorization.js";
 import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
 import { createClientAgentSessionRuntime } from "./client-session/bootstrap.js";
+import { attachClientAgentWorkflowArtifactRuntime } from "./client-workflow-artifact/runtime-composition.js";
+import { bindClientAgentHostRevocations } from "./client-session/host-revocation-composition.js";
 import { registerAgentSessions } from "./agent-session-bootstrap.js";
 import { createAiRuntimeReadinessSources } from "./runtime-readiness-sources.js";
 import { registerAiRuntimeReporting } from "./runtime-reporting-bootstrap.js";
@@ -51,10 +53,12 @@ import { createScreenshotIntakeRuntimeV2 } from "./screenshot-intake-bootstrap.j
 import { requiredEnvironment } from "./required-environment.js";
 import { composeAgentLongSessionRuntime } from "./session-runtime-composition.js";
 import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
-import { createModuleAgentSessionMemoryPort } from "../module-host/agent-session-memory-port.js";
-import { createModuleAuthoritativeSourceInvalidationPort } from "../module-host/agent-source-invalidation-port.js";
 import { composeAgentToolRuntime } from "./runtime-tool-composition.js";
 import { registerProductionAgentWorkflowRuntime } from "./workflow-runtime-bootstrap.js";
+import {
+  createSessionMemoryPortFactory,
+  createSourceInvalidationPortFactory,
+} from "./runtime-public-ports.js";
 export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
   const resolveAgentActor = async (actorId: string) =>
     resolveCurrentSystemActor(input.systemRepositories, actorId);
@@ -75,6 +79,7 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
       aiOperations: undefined,
       aiReadiness: undefined,
       clientAgentSessions: undefined,
+      agentWorkflowProjects: undefined,
       sessionMemory: undefined,
       sourceInvalidation: undefined,
       invalidateAuthorization: undefined,
@@ -113,6 +118,20 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     resolveActor: resolveAgentActor,
   });
   const clientAgentSessions = clientAgentSessionRuntime?.service;
+  const clientWorkflowArtifacts = attachClientAgentWorkflowArtifactRuntime({
+    platform: input,
+    aiRouteApp,
+    hostApp: clientAgentSessionRuntime?.hostApp,
+    routeAuthorizer,
+    sessions: clientAgentSessionRuntime?.service,
+    sessionRepository: clientAgentSessionRuntime?.repository,
+    attemptAuthority: clientAgentSessionRuntime?.attemptAuthority,
+  });
+  const unbindClientAgentHostRevocations = bindClientAgentHostRevocations({
+    adapter: input.clientAgentHostAuth,
+    revokeSessionHost: clientAgentSessionRuntime.revokeHost,
+    revokeWorkflowHost: clientWorkflowArtifacts.revokeHost,
+  });
   const screenshotIntake = createScreenshotIntakeRuntimeV2({
     modules: input.modules,
     runtime: input.runtime,
@@ -146,7 +165,10 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     remote,
     authorizations: runAuthorizations,
     resolveActor: resolveAgentActor,
-    authoritativeSources: input.authoritativeSessionSources,
+    authoritativeSources: [
+      ...clientWorkflowArtifacts.authoritativeSources,
+      ...(input.authoritativeSessionSources ?? []),
+    ],
     memoryObjects: input.sessionMemoryObjects,
   });
   const documentRemote = process.env.DOCUMENT_SERVER_URL?.trim()
@@ -260,6 +282,9 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
       resolveActor: resolveAgentActor,
     },
   );
+  if (agentWorkflowRuntime?.artifacts) {
+    clientWorkflowArtifacts.bindTaskArtifacts?.(agentWorkflowRuntime.artifacts);
+  }
   registerScreenshotIntakeRoutes(aiRouteApp, screenshotIntake);
   registerAgentRunRoutes(
     aiRouteApp,
@@ -309,39 +334,14 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     aiOperations: moduleAi.operations,
     aiReadiness: moduleAi.readiness,
     clientAgentSessions,
-    sessionMemory: longSessions
-      ? (
-          moduleName: string,
-          context: Parameters<typeof createModuleAgentSessionMemoryPort>[1],
-          signal: AbortSignal,
-        ) =>
-          createModuleAgentSessionMemoryPort(
-            moduleName,
-            context,
-            signal,
-            longSessions.memoryProjector,
-          )
-      : undefined,
-    sourceInvalidation: longSessions
-      ? (
-          moduleName: string,
-          context: Parameters<
-            typeof createModuleAuthoritativeSourceInvalidationPort
-          >[1],
-          signal: AbortSignal,
-        ) =>
-          createModuleAuthoritativeSourceInvalidationPort(
-            moduleName,
-            context,
-            signal,
-            longSessions.authoritativeSources,
-            longSessions.invalidationOutbox,
-          )
-      : undefined,
+    agentWorkflowProjects: agentWorkflowRuntime?.projectCommands,
+    sessionMemory: createSessionMemoryPortFactory(longSessions),
+    sourceInvalidation: createSourceInvalidationPortFactory(longSessions),
     invalidateAuthorization: longSessions?.invalidateAuthorization,
     disposeAgentRuntime() {
       screenshotIntake?.dispose();
-      clientAgentSessionRuntime.dispose?.();
+      unbindClientAgentHostRevocations?.();
+      clientWorkflowArtifacts.dispose?.();
       longSessions?.dispose();
     },
   };

package/template/apps/server/src/agent/runtime-public-ports.ts

@@ -0,0 +1,40 @@
+import { createModuleAgentSessionMemoryPort } from "../module-host/agent-session-memory-port.js";
+import { createModuleAuthoritativeSourceInvalidationPort } from "../module-host/agent-source-invalidation-port.js";
+import type { composeAgentLongSessionRuntime } from "./session-runtime-composition.js";
+
+type LongSessionRuntime = ReturnType<typeof composeAgentLongSessionRuntime>;
+
+export function createSessionMemoryPortFactory(runtime: LongSessionRuntime) {
+  if (!runtime) return undefined;
+  return (
+    moduleName: string,
+    context: Parameters<typeof createModuleAgentSessionMemoryPort>[1],
+    signal: AbortSignal,
+  ) =>
+    createModuleAgentSessionMemoryPort(
+      moduleName,
+      context,
+      signal,
+      runtime.memoryProjector,
+    );
+}
+
+export function createSourceInvalidationPortFactory(
+  runtime: LongSessionRuntime,
+) {
+  if (!runtime) return undefined;
+  return (
+    moduleName: string,
+    context: Parameters<
+      typeof createModuleAuthoritativeSourceInvalidationPort
+    >[1],
+    signal: AbortSignal,
+  ) =>
+    createModuleAuthoritativeSourceInvalidationPort(
+      moduleName,
+      context,
+      signal,
+      runtime.authoritativeSources,
+      runtime.invalidationOutbox,
+    );
+}

package/template/apps/server/src/agent/session-invalidation/contracts.ts

@@ -57,6 +57,8 @@ export interface SourceAuthorizationCoordinate {
   readonly actorId: string;
   readonly scopeDigest: string;
   readonly generation: number;
+  /** Optional server-derived scope; authorities that need containment must require it. */
+  readonly scopeSnapshot?: import("@southwind-ai/shared").AuthorizationScopeSnapshot;
 }
 
 type SourceInvalidationEnvelopeBase = {
@@ -102,26 +104,26 @@ export type SessionDerivedInvalidationEnvelopeV1 =
 
 export type SourceInvalidationEnvelopeV1 =
   | (SourceInvalidationEnvelopeBase & {
-        readonly causedBy: SourceInvalidationCausation;
-        readonly transition: {
-          readonly reason: "authorization-revoked";
-          readonly targetState: "revoked";
-        };
-        readonly scope: {
-          /** Sinks converge Session-derived projections for this Actor; source matching alone is insufficient. */
-          readonly kind: "authorization";
-          readonly authorization: SourceAuthorizationCoordinate;
-        };
-      })
+      readonly causedBy: SourceInvalidationCausation;
+      readonly transition: {
+        readonly reason: "authorization-revoked";
+        readonly targetState: "revoked";
+      };
+      readonly scope: {
+        /** Sinks converge Session-derived projections for this Actor; source matching alone is insufficient. */
+        readonly kind: "authorization";
+        readonly authorization: SourceAuthorizationCoordinate;
+      };
+    })
   | (SourceInvalidationEnvelopeBase & {
-        readonly causedBy: SourceInvalidationCausation;
-        readonly transition: Exclude<
-          SourceInvalidationTransition,
-          | { readonly reason: "authorization-revoked" }
-          | { readonly reason: "source-deleted" }
-        >;
-        readonly scope: { readonly kind: "resource" };
-      })
+      readonly causedBy: SourceInvalidationCausation;
+      readonly transition: Exclude<
+        SourceInvalidationTransition,
+        | { readonly reason: "authorization-revoked" }
+        | { readonly reason: "source-deleted" }
+      >;
+      readonly scope: { readonly kind: "resource" };
+    })
   | AuthoritativeSourceDeletionEnvelopeV1
   | SessionDerivedInvalidationEnvelopeV1;
 
@@ -133,10 +135,7 @@ export interface SourceInvalidationDelivery {
   readonly leaseToken: string;
 }
 
-export type SourceInvalidationAppendResult =
-  | "appended"
-  | "duplicate"
-  | "stale";
+export type SourceInvalidationAppendResult = "appended" | "duplicate" | "stale";
 
 /**
  * 由持久化 Adapter 将 append 与触发它的 Session/领域事实写入同一事务。
@@ -171,7 +170,8 @@ export type SourceInvalidationProjectionResult =
   | "stale";
 
 export interface SourceInvalidationProjectionPort<
-  TTarget extends SourceInvalidationProjectionTarget = SourceInvalidationProjectionTarget,
+  TTarget extends SourceInvalidationProjectionTarget =
+    SourceInvalidationProjectionTarget,
 > {
   readonly target: TTarget;
   invalidate(input: {
@@ -181,8 +181,7 @@ export interface SourceInvalidationProjectionPort<
 }
 
 export type SourceInvalidationProjectionPorts = {
-  readonly [TTarget in SourceInvalidationProjectionTarget]:
-    SourceInvalidationProjectionPort<TTarget>;
+  readonly [TTarget in SourceInvalidationProjectionTarget]: SourceInvalidationProjectionPort<TTarget>;
 };
 
 export interface AuthoritativeSourceAccessQuery {