feat: communication spine — gateway, TUI, Discord (#61)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

apps/gateway/src/agent/agent.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { AgentService } from './agent.service.js';
+
+@Global()
+@Module({
+  providers: [AgentService],
+  exports: [AgentService],
+})
+export class AgentModule {}

apps/gateway/src/agent/agent.service.ts

@@ -0,0 +1,131 @@
+import { Injectable, Logger, type OnModuleDestroy } from '@nestjs/common';
+import {
+  createAgentSession,
+  SessionManager,
+  type AgentSession as PiAgentSession,
+  type AgentSessionEvent,
+} from '@mariozechner/pi-coding-agent';
+
+export interface AgentSession {
+  id: string;
+  piSession: PiAgentSession;
+  listeners: Set<(event: AgentSessionEvent) => void>;
+  unsubscribe: () => void;
+}
+
+@Injectable()
+export class AgentService implements OnModuleDestroy {
+  private readonly logger = new Logger(AgentService.name);
+  private readonly sessions = new Map<string, AgentSession>();
+  private readonly creating = new Map<string, Promise<AgentSession>>();
+
+  async createSession(sessionId: string): Promise<AgentSession> {
+    const existing = this.sessions.get(sessionId);
+    if (existing) return existing;
+
+    const inflight = this.creating.get(sessionId);
+    if (inflight) return inflight;
+
+    const promise = this.doCreateSession(sessionId).finally(() => {
+      this.creating.delete(sessionId);
+    });
+    this.creating.set(sessionId, promise);
+    return promise;
+  }
+
+  private async doCreateSession(sessionId: string): Promise<AgentSession> {
+    this.logger.log(`Creating agent session: ${sessionId}`);
+
+    let piSession: PiAgentSession;
+    try {
+      const result = await createAgentSession({
+        sessionManager: SessionManager.inMemory(),
+        tools: [],
+      });
+      piSession = result.session;
+    } catch (err) {
+      this.logger.error(
+        `Failed to create Pi SDK session for ${sessionId}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+      throw new Error(`Agent session creation failed for ${sessionId}: ${String(err)}`);
+    }
+
+    const listeners = new Set<(event: AgentSessionEvent) => void>();
+
+    const unsubscribe = piSession.subscribe((event) => {
+      for (const listener of listeners) {
+        try {
+          listener(event);
+        } catch (err) {
+          this.logger.error(`Event listener error in session ${sessionId}`, err);
+        }
+      }
+    });
+
+    const session: AgentSession = {
+      id: sessionId,
+      piSession,
+      listeners,
+      unsubscribe,
+    };
+
+    this.sessions.set(sessionId, session);
+    this.logger.log(`Agent session ${sessionId} ready`);
+
+    return session;
+  }
+
+  getSession(sessionId: string): AgentSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  async prompt(sessionId: string, message: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`No agent session found: ${sessionId}`);
+    }
+    try {
+      await session.piSession.prompt(message);
+    } catch (err) {
+      this.logger.error(
+        `Pi SDK prompt failed for session=${sessionId}, messageLength=${message.length}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+      throw err;
+    }
+  }
+
+  onEvent(sessionId: string, listener: (event: AgentSessionEvent) => void): () => void {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`No agent session found: ${sessionId}`);
+    }
+    session.listeners.add(listener);
+    return () => session.listeners.delete(listener);
+  }
+
+  async destroySession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.logger.log(`Destroying agent session ${sessionId}`);
+    try {
+      session.unsubscribe();
+    } catch (err) {
+      this.logger.error(`Failed to unsubscribe Pi session ${sessionId}`, String(err));
+    }
+    session.listeners.clear();
+    this.sessions.delete(sessionId);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    this.logger.log('Shutting down all agent sessions');
+    const stops = Array.from(this.sessions.keys()).map((id) => this.destroySession(id));
+    const results = await Promise.allSettled(stops);
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        this.logger.error('Session shutdown failure', String(result.reason));
+      }
+    }
+  }
+}

apps/gateway/src/app.module.ts

@@ -1,7 +1,10 @@
 import { Module } from '@nestjs/common';
 import { HealthController } from './health/health.controller.js';
+import { AgentModule } from './agent/agent.module.js';
+import { ChatModule } from './chat/chat.module.js';
 
 @Module({
+  imports: [AgentModule, ChatModule],
   controllers: [HealthController],
 })
 export class AppModule {}

apps/gateway/src/chat/chat.controller.ts

@@ -0,0 +1,75 @@
+import { Controller, Post, Body, Logger, HttpException, HttpStatus } from '@nestjs/common';
+import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import { AgentService } from '../agent/agent.service.js';
+import { v4 as uuid } from 'uuid';
+
+interface ChatRequest {
+  conversationId?: string;
+  content: string;
+}
+
+interface ChatResponse {
+  conversationId: string;
+  text: string;
+}
+
+@Controller('api/chat')
+export class ChatController {
+  private readonly logger = new Logger(ChatController.name);
+
+  constructor(private readonly agentService: AgentService) {}
+
+  @Post()
+  async chat(@Body() body: ChatRequest): Promise<ChatResponse> {
+    const conversationId = body.conversationId ?? uuid();
+
+    try {
+      let agentSession = this.agentService.getSession(conversationId);
+      if (!agentSession) {
+        agentSession = await this.agentService.createSession(conversationId);
+      }
+    } catch (err) {
+      this.logger.error(
+        `Session creation failed for conversation=${conversationId}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+      throw new HttpException('Agent session unavailable', HttpStatus.SERVICE_UNAVAILABLE);
+    }
+
+    let responseText = '';
+
+    const done = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        this.logger.error(`Agent response timed out after 120s for conversation=${conversationId}`);
+        reject(new Error('Agent response timed out'));
+      }, 120_000);
+
+      const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
+        if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta') {
+          responseText += event.assistantMessageEvent.delta;
+        }
+        if (event.type === 'agent_end') {
+          clearTimeout(timer);
+          cleanup();
+          resolve();
+        }
+      });
+    });
+
+    try {
+      await this.agentService.prompt(conversationId, body.content);
+      await done;
+    } catch (err) {
+      if (err instanceof HttpException) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes('timed out')) {
+        throw new HttpException('Agent response timed out', HttpStatus.GATEWAY_TIMEOUT);
+      }
+      this.logger.error(`Chat prompt failed for conversation=${conversationId}`, String(err));
+      throw new HttpException('Agent processing failed', HttpStatus.INTERNAL_SERVER_ERROR);
+    }
+
+    return { conversationId, text: responseText };
+  }
+}

apps/gateway/src/chat/chat.gateway.ts

@@ -0,0 +1,164 @@
+import { Logger } from '@nestjs/common';
+import {
+  WebSocketGateway,
+  WebSocketServer,
+  SubscribeMessage,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  type OnGatewayInit,
+  ConnectedSocket,
+  MessageBody,
+} from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import { AgentService } from '../agent/agent.service.js';
+import { v4 as uuid } from 'uuid';
+
+interface ChatMessage {
+  conversationId?: string;
+  content: string;
+}
+
+@WebSocketGateway({
+  cors: { origin: '*' },
+  namespace: '/chat',
+})
+export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
+  @WebSocketServer()
+  server!: Server;
+
+  private readonly logger = new Logger(ChatGateway.name);
+  private readonly clientSessions = new Map<
+    string,
+    { conversationId: string; cleanup: () => void }
+  >();
+
+  constructor(private readonly agentService: AgentService) {}
+
+  afterInit(): void {
+    this.logger.log('Chat WebSocket gateway initialized');
+  }
+
+  handleConnection(client: Socket): void {
+    this.logger.log(`Client connected: ${client.id}`);
+  }
+
+  handleDisconnect(client: Socket): void {
+    this.logger.log(`Client disconnected: ${client.id}`);
+    const session = this.clientSessions.get(client.id);
+    if (session) {
+      session.cleanup();
+      this.clientSessions.delete(client.id);
+    }
+  }
+
+  @SubscribeMessage('message')
+  async handleMessage(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() data: ChatMessage,
+  ): Promise<void> {
+    const conversationId = data.conversationId ?? uuid();
+
+    this.logger.log(`Message from ${client.id} in conversation ${conversationId}`);
+
+    // Ensure agent session exists for this conversation
+    try {
+      let agentSession = this.agentService.getSession(conversationId);
+      if (!agentSession) {
+        agentSession = await this.agentService.createSession(conversationId);
+      }
+    } catch (err) {
+      this.logger.error(
+        `Session creation failed for client=${client.id}, conversation=${conversationId}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+      client.emit('error', {
+        conversationId,
+        error: 'Failed to start agent session. Please try again.',
+      });
+      return;
+    }
+
+    // Always clean up previous listener to prevent leak
+    const existing = this.clientSessions.get(client.id);
+    if (existing) {
+      existing.cleanup();
+    }
+
+    // Subscribe to agent events and relay to client
+    const cleanup = this.agentService.onEvent(conversationId, (event: AgentSessionEvent) => {
+      this.relayEvent(client, conversationId, event);
+    });
+
+    this.clientSessions.set(client.id, { conversationId, cleanup });
+
+    // Send acknowledgment
+    client.emit('message:ack', { conversationId, messageId: uuid() });
+
+    // Dispatch to agent
+    try {
+      await this.agentService.prompt(conversationId, data.content);
+    } catch (err) {
+      this.logger.error(
+        `Agent prompt failed for client=${client.id}, conversation=${conversationId}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+      client.emit('error', {
+        conversationId,
+        error: 'The agent failed to process your message. Please try again.',
+      });
+    }
+  }
+
+  private relayEvent(client: Socket, conversationId: string, event: AgentSessionEvent): void {
+    if (!client.connected) {
+      this.logger.warn(
+        `Dropping event ${event.type} for disconnected client=${client.id}, conversation=${conversationId}`,
+      );
+      return;
+    }
+
+    switch (event.type) {
+      case 'agent_start':
+        client.emit('agent:start', { conversationId });
+        break;
+
+      case 'agent_end':
+        client.emit('agent:end', { conversationId });
+        break;
+
+      case 'message_update': {
+        const assistantEvent = event.assistantMessageEvent;
+        if (assistantEvent.type === 'text_delta') {
+          client.emit('agent:text', {
+            conversationId,
+            text: assistantEvent.delta,
+          });
+        } else if (assistantEvent.type === 'thinking_delta') {
+          client.emit('agent:thinking', {
+            conversationId,
+            text: assistantEvent.delta,
+          });
+        }
+        break;
+      }
+
+      case 'tool_execution_start':
+        client.emit('agent:tool:start', {
+          conversationId,
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+        });
+        break;
+
+      case 'tool_execution_end':
+        client.emit('agent:tool:end', {
+          conversationId,
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          isError: event.isError,
+        });
+        break;
+    }
+  }
+}

apps/gateway/src/chat/chat.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { ChatGateway } from './chat.gateway.js';
+import { ChatController } from './chat.controller.js';
+
+@Module({
+  controllers: [ChatController],
+  providers: [ChatGateway],
+})
+export class ChatModule {}