feat(tess): wire durable interaction surfaces (#732)

apps/gateway/src/agent/interaction.controller.ts

@@ -4,17 +4,21 @@ import {
   ForbiddenException,
   Get,
   Headers,
+  Sse,
   Inject,
   Param,
   Post,
   Query,
   UseGuards,
+  UseFilters,
 } from '@nestjs/common';
-import type { RuntimeAttachMode } from '@mosaicstack/types';
+import type { RuntimeAttachMode, RuntimeStreamEvent } from '@mosaicstack/types';
+import { Observable } from 'rxjs';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
 import { scopeFromUser, type AuthenticatedUserLike } from '../auth/session-scope.js';
 import { TessDurableSessionService } from './tess-durable-session.service.js';
+import { RuntimeApprovalDeniedFilter } from './runtime-approval-denied.filter.js';
 import {
   RuntimeProviderService,
   type RuntimeProviderRequestContext,
@@ -26,6 +30,7 @@ import {
  */
 @Controller('api/interaction/:agentName')
 @UseGuards(AuthGuard)
+@UseFilters(RuntimeApprovalDeniedFilter)
 export class InteractionController {
   constructor(
     @Inject(RuntimeProviderService) private readonly runtime: RuntimeProviderService,
@@ -60,6 +65,41 @@ export class InteractionController {
     );
   }
 
+  /**
+   * Bind an existing, authorized runtime session to the stable conversation ID.
+   * This is the lifecycle boundary where both runtime identifiers are known.
+   */
+  @Post('sessions/:sessionId/enroll')
+  async enroll(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Body() body: { providerId?: string; runtimeSessionId?: string } = {},
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ) {
+    this.assertConfiguredAgent(agentName);
+    const providerId = this.requiredProvider(body.providerId ?? '');
+    const runtimeSessionId = body.runtimeSessionId?.trim();
+    if (!runtimeSessionId) throw new ForbiddenException('Runtime session identity is required');
+    const context = this.context(user, correlationId);
+    const sessions = await this.runtime.listSessions(providerId, context);
+    if (!sessions.some((session): boolean => session.id === runtimeSessionId)) {
+      throw new ForbiddenException('Runtime session is not visible to this actor');
+    }
+    await this.durable.enroll(
+      {
+        agentName,
+        sessionId,
+        tenantId: context.actorScope.tenantId,
+        ownerId: context.actorScope.userId,
+        providerId,
+        runtimeSessionId,
+      },
+      context,
+    );
+    return { status: 'enrolled', sessionId };
+  }
+
   @Post('sessions/:sessionId/attach')
   async attach(
     @Param('agentName') agentName: string,
@@ -84,6 +124,53 @@ export class InteractionController {
     );
   }
 
+  @Sse('sessions/:sessionId/stream')
+  stream(
+    @Param('agentName') agentName: string,
+    @Param('sessionId') sessionId: string,
+    @Query('cursor') cursor: string | undefined,
+    @CurrentUser() user: AuthenticatedUserLike,
+    @Headers('x-correlation-id') correlationId?: string,
+  ): Observable<{ data: RuntimeStreamEvent }> {
+    this.assertConfiguredAgent(agentName);
+    const context = this.context(user, correlationId);
+    return new Observable((subscriber) => {
+      let iterator: AsyncIterator<RuntimeStreamEvent> | undefined;
+      let cancelled = false;
+      void (async (): Promise<void> => {
+        try {
+          const snapshot = await this.durable.getSnapshot(sessionId, context);
+          if (cancelled || subscriber.closed) return;
+          this.assertSessionAgent(snapshot.identity.agentName, agentName);
+          iterator = this.runtime
+            .streamSession(
+              snapshot.identity.providerId,
+              snapshot.identity.runtimeSessionId,
+              cursor?.trim() || undefined,
+              context,
+            )
+            [Symbol.asyncIterator]();
+          if (cancelled || subscriber.closed) {
+            await iterator.return?.();
+            return;
+          }
+          while (!cancelled && !subscriber.closed) {
+            const next = await iterator.next();
+            if (next.done || cancelled || subscriber.closed) break;
+            subscriber.next({ data: next.value });
+          }
+          if (!subscriber.closed) subscriber.complete();
+        } catch (error: unknown) {
+          if (!subscriber.closed) subscriber.error(error);
+        }
+      })();
+      return (): void => {
+        cancelled = true;
+        void iterator?.return?.();
+      };
+    });
+  }
+
   @Post('sessions/:sessionId/send')
   async send(
     @Param('agentName') agentName: string,