create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent/operation-catalog.ts

@@ -0,0 +1,135 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AgentAdminAvailabilityReason,
+  AgentAdminOperationCatalogItem,
+} from "@southwind-ai/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  buildRegisteredOperations,
+  type RegisteredOperation,
+} from "./run-operation-registry.js";
+import { catalogGuardReason } from "./tool-catalog-availability.js";
+
+export interface AgentAdminOperationCatalogInput {
+  readonly modules: readonly ModuleManifest[];
+  readonly hosts: InitializedModuleHosts;
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly runtimeAvailable: () => boolean;
+  /** Optional current readiness projection; no Provider execution or grants. */
+  readonly operationReadiness?: (
+    operationKey: string,
+    context: RequestGuardContext,
+  ) => Promise<boolean>;
+}
+
+export class AgentAdminOperationCatalog {
+  readonly #operations: ReadonlyMap<string, RegisteredOperation>;
+  readonly #schemas: ReadonlyMap<
+    string,
+    NonNullable<ModuleManifest["jsonSchemas"]>[number]["schema"]
+  >;
+
+  constructor(private readonly input: AgentAdminOperationCatalogInput) {
+    this.#operations = buildRegisteredOperations(input.modules, input.hosts);
+    this.#schemas = new Map(
+      input.modules.flatMap(({ jsonSchemas }) =>
+        (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+      ),
+    );
+  }
+
+  async list(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentAdminOperationCatalogItem[]> {
+    return Promise.all(
+      [...this.#operations.values()].map(async (operation) => {
+        const definition = operation.definition;
+        const module = this.input.modules.find(({ aiOperations }) =>
+          aiOperations?.some(({ key }) => key === definition.key),
+        )!;
+        const inputSchema = this.#schemas.get(definition.inputSchemaKey);
+        const outputSchema = this.#schemas.get(definition.outputSchemaKey);
+        const availabilityReason = await this.availability(operation, context);
+        return {
+          key: definition.key,
+          module: module.name,
+          moduleLabel: module.label,
+          kind: definition.kind,
+          visibility: definition.visibility ?? "public",
+          execution: definition.execution,
+          featureKey: definition.featureKey,
+          permissionKey: definition.permissionKey,
+          auditAction: definition.auditAction,
+          dataClassification: definition.dataClassification,
+          requiredCapabilities: [...definition.requiredCapabilities],
+          inputModalities: [...(definition.inputModalities ?? ["text"])],
+          inputSchemaKey: definition.inputSchemaKey,
+          outputSchemaKey: definition.outputSchemaKey,
+          ...(inputSchema ? { inputSchema: structuredClone(inputSchema) } : {}),
+          ...(outputSchema
+            ? { outputSchema: structuredClone(outputSchema) }
+            : {}),
+          allowedToolKeys: [...definition.allowedToolKeys],
+          limits: { ...definition.limits },
+          launchAuthority:
+            definition.clientExecution?.launchAuthority ?? "direct",
+          selectable: availabilityReason === "allowed",
+          availabilityReason,
+        };
+      }),
+    );
+  }
+
+  private async availability(
+    operation: RegisteredOperation,
+    context: RequestGuardContext,
+  ): Promise<AgentAdminAvailabilityReason> {
+    const { definition } = operation;
+    if (!operation.feature) return "governance-unavailable";
+    const access = await evaluateAccessGuards(
+      this.input.runtime,
+      context,
+      {
+        feature: operation.feature,
+        permission: { permissionKey: definition.permissionKey },
+      },
+      { record: false },
+    );
+    if (!access.decision.allowed)
+      return catalogGuardReason(access.decision.reason);
+    if (definition.visibility === "internal") return "internal-operation";
+    if (definition.kind !== "agent") return "unsupported-operation";
+    if (definition.clientExecution?.launchAuthority === "workflow-artifact")
+      return "workflow-only";
+    if (!operation.registration?.prepare || !operation.moduleName)
+      return "handler-unavailable";
+    if (!isServerScopeContext(context.actor.scopeContext))
+      return "scope-unavailable";
+    if (
+      !this.#schemas.has(definition.inputSchemaKey) ||
+      !this.#schemas.has(definition.outputSchemaKey)
+    )
+      return "governance-unavailable";
+    if (
+      definition.providerEgress?.mode === "configured-endpoint" &&
+      !definition.providerDataPolicy
+    )
+      return "governance-unavailable";
+    if (definition.isolatedExecution || !this.input.runtimeAvailable())
+      return "runtime-unavailable";
+    if (definition.readiness) {
+      if (!this.input.operationReadiness) return "runtime-unavailable";
+      try {
+        if (!(await this.input.operationReadiness(definition.key, context)))
+          return "runtime-unavailable";
+      } catch {
+        return "runtime-unavailable";
+      }
+    }
+    return "allowed";
+  }
+}

package/template/apps/server/src/agent/remote-runtime-response.ts

@@ -36,7 +36,7 @@ export function parseRemoteStatus(value: unknown): AgentRuntimeStatusResponse {
     throw new Error("Agent Runtime 状态字段无效");
   }
   const terminalEvent =
-    value.terminalEvent === undefined
+    value.terminalEvent === undefined || value.terminalEvent === null
       ? undefined
       : parseTerminalEvent(value.terminalEvent, runId);
   const terminalStatus = ["completed", "failed", "cancelled"].includes(status);

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

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { AgentRunFacade } from "./run-facade.js";
+import { assertBrowserVisibleOperation } from "./run-browser-visibility.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { AgentAdminOperationCatalog } from "./operation-catalog.js";
+
+describe("Internal operations remain private to trusted orchestration", () => {
+  test("Public/default operations remain browser-visible", async () => {
+    const { facade } = await createRunFacadeFixture();
+    expect(facade.operationPolicy("business.answer")?.visibility).toBe(
+      "public",
+    );
+    expect(() =>
+      assertBrowserVisibleOperation(facade, "business.answer"),
+    ).not.toThrow();
+  });
+
+  test("Internal declaration blocks browser access and Admin selection without blocking governed server orchestration", async () => {
+    const { hosts, runtime, remote, context } = await createRunFacadeFixture();
+    const module = runFacadeManifest();
+    module.aiOperations![0]!.visibility = "internal";
+    const facade = new AgentRunFacade(
+      [module],
+      hosts,
+      runtime,
+      remote,
+      createTestRunAuthorizationStore(),
+    );
+    expect(() =>
+      assertBrowserVisibleOperation(facade, "business.answer"),
+    ).toThrow("Agent Run 不存在或不可访问");
+    const catalog = new AgentAdminOperationCatalog({
+      modules: [module],
+      hosts,
+      runtime,
+      runtimeAvailable: () => true,
+    });
+    expect((await catalog.list(context))[0]).toMatchObject({
+      visibility: "internal",
+      selectable: false,
+      availabilityReason: "internal-operation",
+    });
+    await facade.start(
+      "business.answer",
+      { question: "可信服务端编排" },
+      "server-orchestration",
+      context,
+    );
+    expect(remote.started).toHaveLength(1);
+    context.actor.permissionKeys = [];
+    await expect(
+      facade.start("business.answer", { question: "无权" }, "denied", context),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+});

package/template/apps/server/src/agent/run-browser-visibility.ts

@@ -0,0 +1,11 @@
+import type { AgentRunFacade } from "./run-facade.js";
+import { inaccessibleRun } from "./run-errors.js";
+
+export function assertBrowserVisibleOperation(
+  facade: AgentRunFacade,
+  operationKey: string,
+) {
+  if (facade.operationPolicy(operationKey)?.visibility === "internal") {
+    throw inaccessibleRun();
+  }
+}

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

@@ -24,6 +24,7 @@ export interface AgentRuntimeOperation {
     key: string;
     label: string;
     description: string;
+    inputSchema?: ModuleAiJsonValue;
     approval: "none" | "required";
     idempotency: "none" | "supported" | "required";
     approvalTimeoutSeconds?: number;

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

@@ -10,10 +10,19 @@ export function toolDefinitions(
   const tools = new Map(
     modules.flatMap(({ tools }) => tools.map((tool) => [tool.key, tool])),
   );
+  const schemas = new Map(
+    modules.flatMap(({ jsonSchemas }) =>
+      (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+    ),
+  );
   return allowedKeys.map((key) => {
     const tool = tools.get(key);
     if (!tool) throw new Error(`AI Operation 引用了未知 Tool：${key}`);
+    const inputSchema = schemas.get(tool.inputSchemaKey);
+    if (!inputSchema)
+      throw new Error(`AI Operation Tool 缺少输入 Schema：${key}`);
     return {
+      inputSchema,
       key: tool.key,
       label: tool.label,
       description: tool.description,

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

@@ -12,6 +12,7 @@ export function publicAgentOperationPolicy(
     allowedToolKeys: [...operation.definition.allowedToolKeys],
     featureKey: operation.definition.featureKey,
     permissionKey: operation.definition.permissionKey,
+    visibility: operation.definition.visibility ?? "public",
     deploymentKey:
       provider.mode === "configured-endpoint"
         ? provider.deploymentKey

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

@@ -0,0 +1,35 @@
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export function facadeError(error: unknown): Response {
+  if (error instanceof AgentRunFacadeError) {
+    return errorResponse(error.code, error.message, error.status);
+  }
+  return errorResponse(
+    "RUNTIME_UNAVAILABLE",
+    "Agent Runtime 暂不可用",
+    503,
+    true,
+  );
+}
+
+export function errorResponse(
+  code: string,
+  message: string,
+  status: number,
+  retryable = false,
+): Response {
+  return Response.json(
+    { code, message, requestId: crypto.randomUUID(), retryable },
+    { status },
+  );
+}
+
+export function required(value: string | undefined): string {
+  if (!value)
+    throw new AgentRunFacadeError("INVALID_INPUT", "Run ID 无效", 400);
+  return value;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -1,3 +1,9 @@
+import {
+  facadeError,
+  errorResponse,
+  required,
+  isRecord,
+} from "./run-route-response.js";
 import { timingSafeEqual } from "node:crypto";
 import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/routes.js";
@@ -7,6 +13,8 @@ import type { AgentRuntimePort } from "./run-contracts.js";
 import type { AgentRunSessionLinkPort } from "./session-run-link.js";
 import type { SessionRunResultMemoryPort } from "./session-result-memory.js";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { projectPublicRunEvents } from "./workbench-sse.js";
+import { assertBrowserVisibleOperation } from "./run-browser-visibility.js";
 import {
   AgentToolHostError,
   attachExecutionGrant,
@@ -46,6 +54,7 @@ export function registerAgentRunRoutes(
     const context = raw as RouteContext;
     try {
       const request = parseStartRequest(context.body);
+      assertBrowserVisibleOperation(facade, request.operationKey);
       const idempotencyKey = context.request.headers.get("idempotency-key");
       if (!idempotencyKey?.trim()) {
         return errorResponse("INVALID_INPUT", "幂等键不能为空", 400);
@@ -70,12 +79,15 @@ export function registerAgentRunRoutes(
     try {
       const runId = required(context.params.runId);
       const operationKey = parseOperationKey(context.query.operationKey);
+      assertBrowserVisibleOperation(facade, operationKey);
       await facade.authorizeRun(operationKey, runId, context.guardContext);
       const cursor = parseCursor(
         context.query.after,
         context.request.headers.get("last-event-id"),
       );
-      return await remote.events(runId, cursor, context.request.signal);
+      return projectPublicRunEvents(
+        await remote.events(runId, cursor, context.request.signal),
+      );
     } catch (error) {
       return facadeError(error);
     }
@@ -86,6 +98,7 @@ export function registerAgentRunRoutes(
     try {
       const runId = required(context.params.runId);
       const operationKey = parseOperationKey(context.query.operationKey);
+      assertBrowserVisibleOperation(facade, operationKey);
       const sessionId = context.query.sessionId
         ? parseSessionId(context.query.sessionId)
         : undefined;
@@ -105,8 +118,14 @@ export function registerAgentRunRoutes(
           status.status === "cancelled"
         ) {
           if (status.status === "completed") {
-            await projectResult(resultMemory, boundSessionId, runId,
-              status.lastSequence, response, context);
+            await projectResult(
+              resultMemory,
+              boundSessionId,
+              runId,
+              status.lastSequence,
+              response,
+              context,
+            );
           }
           await completeSessionRun(
             sessionLinks,
@@ -128,6 +147,7 @@ export function registerAgentRunRoutes(
     try {
       const runId = required(context.params.runId);
       const operationKey = parseOperationKey(context.query.operationKey);
+      assertBrowserVisibleOperation(facade, operationKey);
       const sessionId = context.query.sessionId
         ? parseSessionId(context.query.sessionId)
         : undefined;
@@ -141,7 +161,11 @@ export function registerAgentRunRoutes(
         isRecord(context.body) && typeof context.body.reason === "string"
           ? context.body.reason.slice(0, 200)
           : undefined;
-      const response = await remote.cancel(runId, reason, context.request.signal);
+      const response = await remote.cancel(
+        runId,
+        reason,
+        context.request.signal,
+      );
       if (authorized.sessionId && response.ok) {
         const status = await remote.status(runId, context.request.signal);
         if (!["completed", "failed", "cancelled"].includes(status.status)) {
@@ -149,8 +173,14 @@ export function registerAgentRunRoutes(
         }
         if (status.status === "completed") {
           const result = await remote.result(runId, context.request.signal);
-          await projectResult(resultMemory, authorized.sessionId, runId,
-            status.lastSequence, result, context);
+          await projectResult(
+            resultMemory,
+            authorized.sessionId,
+            runId,
+            status.lastSequence,
+            result,
+            context,
+          );
         }
         await completeSessionRun(
           sessionLinks,
@@ -171,6 +201,7 @@ export function registerAgentRunRoutes(
     try {
       const runId = required(context.params.runId);
       const request = parseAttachRequest(context.body);
+      assertBrowserVisibleOperation(facade, request.operationKey);
       const authorized = await facade.authorizeRunMutation(
         request.operationKey,
         runId,
@@ -188,8 +219,14 @@ export function registerAgentRunRoutes(
       if (authorized.sessionId && attached.terminalEvent) {
         if (attached.status === "completed") {
           const response = await remote.result(runId, context.request.signal);
-          await projectResult(resultMemory, authorized.sessionId, runId,
-            attached.terminalEvent.sequence, response, context);
+          await projectResult(
+            resultMemory,
+            authorized.sessionId,
+            runId,
+            attached.terminalEvent.sequence,
+            response,
+            context,
+          );
         }
         await completeSessionRun(
           sessionLinks,
@@ -267,7 +304,7 @@ async function projectResult(
     sessionId,
     runId,
     terminalSequence,
-    result: await response.clone().json() as ModuleAiJsonValue,
+    result: (await response.clone().json()) as ModuleAiJsonValue,
     context: context.guardContext,
     signal: context.request.signal,
   });
@@ -302,37 +339,3 @@ export function validInternalToken(
   const right = Buffer.from(expected);
   return left.length === right.length && timingSafeEqual(left, right);
 }
-
-function facadeError(error: unknown): Response {
-  if (error instanceof AgentRunFacadeError) {
-    return errorResponse(error.code, error.message, error.status);
-  }
-  return errorResponse(
-    "RUNTIME_UNAVAILABLE",
-    "Agent Runtime 暂不可用",
-    503,
-    true,
-  );
-}
-
-function errorResponse(
-  code: string,
-  message: string,
-  status: number,
-  retryable = false,
-): Response {
-  return Response.json(
-    { code, message, requestId: crypto.randomUUID(), retryable },
-    { status },
-  );
-}
-
-function required(value: string | undefined): string {
-  if (!value)
-    throw new AgentRunFacadeError("INVALID_INPUT", "Run ID 无效", 400);
-  return value;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

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

@@ -1,4 +1,6 @@
 import { resolveCurrentSystemActor } from "../system/actor.js";
+import type { AgentAdminReadinessRef } from "./admin-catalog-bootstrap.js";
+import { registerAgentAdminCatalogRuntime } from "./admin-catalog-bootstrap.js";
 import { AiArtifactCodec } from "../ai-artifact/codec.js";
 import { registerAiArtifactRoutes } from "../ai-artifact/routes.js";
 import { AiArtifactRuntime } from "../ai-artifact/runtime.js";
@@ -41,7 +43,7 @@ import { InMemoryAgentRunBindingRepository } from "./run-binding-repository.js";
 import { AgentBackgroundOperationExecutor } from "./background-operation.js";
 import { createModuleAiPorts } from "./module-ai-port-factory.js";
 import { createManifestAuthorizedRouteApp } from "../module-host/static-route-authorization.js";
-import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
+import { disableAgentRuntime } from "./runtime-disabled-composition.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";
@@ -52,6 +54,7 @@ import { registerScreenshotIntakeRoutes } from "./screenshot-intake-routes.js";
 import { createScreenshotIntakeRuntimeV2 } from "./screenshot-intake-bootstrap.js";
 import { requiredEnvironment } from "./required-environment.js";
 import { composeAgentLongSessionRuntime } from "./session-runtime-composition.js";
+import { registerAgentWorkbenchRuntime } from "./workbench-bootstrap.js";
 import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
 import { composeAgentToolRuntime } from "./runtime-tool-composition.js";
 import { registerProductionAgentWorkflowRuntime } from "./workflow-runtime-bootstrap.js";
@@ -62,33 +65,23 @@ import {
 export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
   const resolveAgentActor = async (actorId: string) =>
     resolveCurrentSystemActor(input.systemRepositories, actorId);
-  const { features, toolHandlers, toolRegistry, routeAuthorizer } =
-    composeAgentToolRuntime(input);
+  const tools = composeAgentToolRuntime(input);
+  const { features, toolHandlers, toolRegistry, routeAuthorizer } = tools;
+  const catalogReadiness: AgentAdminReadinessRef = {};
+  registerAgentAdminCatalogRuntime(input, tools, catalogReadiness);
   const aiRouteApp = createManifestAuthorizedRouteApp(
     input.app,
     routeAuthorizer,
   );
   if (!input.platformConfig.enableAI) {
-    registerProductionAgentWorkflowRuntime(input, aiRouteApp, toolRegistry);
-    registerUnavailableAiRoutes(
-      createManifestAuthorizedRouteApp(input.app, routeAuthorizer),
-    );
-    return {
-      toolHandlers,
-      aiArtifacts: undefined,
-      aiOperations: undefined,
-      aiReadiness: undefined,
-      clientAgentSessions: undefined,
-      agentWorkflowProjects: undefined,
-      sessionMemory: undefined,
-      sourceInvalidation: undefined,
-      invalidateAuthorization: undefined,
-      disposeAgentRuntime: undefined,
-    };
+    return disableAgentRuntime(input, aiRouteApp, tools);
   }
   const sessionSecret = requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET");
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
-  registerAgentSessions({ ...input, secret: internalToken });
+  const businessSessions = registerAgentSessions({
+    ...input,
+    secret: internalToken,
+  });
   const aiArtifacts = new AiArtifactRuntime(
     new AiArtifactCodec(sessionSecret),
     input.hosts,
@@ -203,6 +196,7 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     trustStore: readinessTrustStore,
     runtime: input.runtime,
   });
+  catalogReadiness.current = aiReadiness;
   const outputRuntime = createDocumentOutputRuntime({
     modules: input.modules,
     readiness: aiReadiness,
@@ -286,6 +280,13 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
   if (agentWorkflowRuntime?.artifacts) {
     clientWorkflowArtifacts.bindTaskArtifacts?.(agentWorkflowRuntime.artifacts);
   }
+  registerAgentWorkbenchRuntime(input, aiRouteApp, {
+    agentFacade,
+    remote,
+    business: businessSessions,
+    sessions: longSessions?.facade,
+    workflows: agentWorkflowRuntime?.query,
+  });
   registerScreenshotIntakeRoutes(aiRouteApp, screenshotIntake);
   registerAgentRunRoutes(
     aiRouteApp,

package/template/apps/server/src/agent/runtime-disabled-composition.ts

@@ -0,0 +1,28 @@
+import type { RouteApp } from "../system/routes.js";
+import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
+import type { composeAgentToolRuntime } from "./runtime-tool-composition.js";
+import { registerAgentWorkbenchRuntime } from "./workbench-bootstrap.js";
+import { registerProductionAgentWorkflowRuntime } from "./workflow-runtime-bootstrap.js";
+import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
+
+export function disableAgentRuntime(
+  input: AgentPlatformRuntimeInput,
+  app: RouteApp,
+  tools: ReturnType<typeof composeAgentToolRuntime>,
+) {
+  registerAgentWorkbenchRuntime(input, app);
+  registerProductionAgentWorkflowRuntime(input, app, tools.toolRegistry);
+  registerUnavailableAiRoutes(app);
+  return {
+    toolHandlers: tools.toolHandlers,
+    aiArtifacts: undefined,
+    aiOperations: undefined,
+    aiReadiness: undefined,
+    clientAgentSessions: undefined,
+    agentWorkflowProjects: undefined,
+    sessionMemory: undefined,
+    sourceInvalidation: undefined,
+    invalidateAuthorization: undefined,
+    disposeAgentRuntime: undefined,
+  };
+}

package/template/apps/server/src/agent/runtime-tool-composition.ts

@@ -1,3 +1,4 @@
+import { bindAgentGovernanceTools } from "./governance-runtime.js";
 import { createModuleToolHandlerMap } from "../module-host.js";
 import { PlatformMcpAdapter } from "../mcp/adapter.js";
 import { registerMcpRoutes } from "../mcp/routes.js";
@@ -25,6 +26,7 @@ export function composeAgentToolRuntime(input: AgentPlatformRuntimeInput) {
     toolHandlers,
     input.runtime,
   );
+  bindAgentGovernanceTools(input.runtime, toolRegistry);
   const routeAuthorizer = createStaticRouteAuthorizer(
     input.runtime,
     input.modules,

package/template/apps/server/src/agent/session-projection-facade.ts

@@ -1,4 +1,5 @@
-import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { projectSessionRecording } from "./session-recording-reader.js";
+import { sessionProjectionGovernance as governance } from "./session-projection-governance.js";
 import type { RequestGuardContext } from "../guards.js";
 import type { MemoryObjectAuthorizationPort } from "./context-memory/contracts.js";
 import {
@@ -89,6 +90,12 @@ export class AgentSessionProjectionFacade {
     };
   }
 
+  async recording(sessionId: string, context: RequestGuardContext) {
+    return projectSessionRecording(
+      await this.replay(sessionId, undefined, context),
+    );
+  }
+
   async contextVersions(sessionId: string, context: RequestGuardContext) {
     const session = await this.requireSession(sessionId, context);
     const rows = await this.contexts.listForSession(session.sessionId);
@@ -339,11 +346,3 @@ export class AgentSessionProjectionFacade {
     return session;
   }
 }
-
-function governance(context: RequestGuardContext) {
-  return {
-    actorId: context.actor.id,
-    scopeDigest:
-      `sha256:${captureAuthorizationScope(context.actor.scopeContext).hash}` as const,
-  };
-}

package/template/apps/server/src/agent/session-projection-governance.ts

@@ -0,0 +1,10 @@
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+
+export function sessionProjectionGovernance(context: RequestGuardContext) {
+  return {
+    actorId: context.actor.id,
+    scopeDigest:
+      `sha256:${captureAuthorizationScope(context.actor.scopeContext).hash}` as const,
+  };
+}