feat(#382): Herald Service: broadcast to all active chat providers

- Replace direct DiscordService injection with CHAT_PROVIDERS array
- Herald broadcasts to ALL active chat providers (Discord, Matrix, future)
- Graceful error handling — one provider failure doesn't block others
- Skips disconnected providers automatically
- Tests verify multi-provider broadcasting behavior
- Fix lint: remove unnecessary conditional in matrix.service.ts

Refs #382

apps/api/src/bridge/matrix/matrix.service.ts

@@ -1,6 +1,10 @@
-import { Injectable, Logger } from "@nestjs/common";
+import { Injectable, Logger, Optional, Inject } from "@nestjs/common";
 import { MatrixClient, SimpleFsStorageProvider, AutojoinRoomsMixin } from "matrix-bot-sdk";
 import { StitcherService } from "../../stitcher/stitcher.service";
+import { CommandParserService } from "../parser/command-parser.service";
+import { CommandAction } from "../parser/command.interface";
+import type { ParsedCommand } from "../parser/command.interface";
+import { MatrixRoomService } from "./matrix-room.service";
 import { sanitizeForLogging } from "../../common/utils";
 import type {
   IChatProvider,
@@ -46,7 +50,8 @@ interface MatrixRoomEvent {
  *
  * Responsibilities:
  * - Connect to Matrix via access token
- * - Listen for commands in designated rooms
+ * - Listen for commands in mapped rooms (via MatrixRoomService)
+ * - Parse commands using shared CommandParserService
  * - Forward commands to stitcher
  * - Receive status updates from herald
  * - Post updates to threads (MSC3440)
@@ -62,7 +67,15 @@ export class MatrixService implements IChatProvider {
   private readonly controlRoomId: string;
   private readonly workspaceId: string;
 
-  constructor(private readonly stitcherService: StitcherService) {
+  constructor(
+    private readonly stitcherService: StitcherService,
+    @Optional()
+    @Inject(CommandParserService)
+    private readonly commandParser: CommandParserService | null,
+    @Optional()
+    @Inject(MatrixRoomService)
+    private readonly matrixRoomService: MatrixRoomService | null
+  ) {
     this.homeserverUrl = process.env.MATRIX_HOMESERVER_URL ?? "";
     this.accessToken = process.env.MATRIX_ACCESS_TOKEN ?? "";
     this.botUserId = process.env.MATRIX_BOT_USER_ID ?? "";
@@ -113,30 +126,10 @@ export class MatrixService implements IChatProvider {
       // Ignore messages from the bot itself
       if (event.sender === this.botUserId) return;
 
-      // Check if message is in control room
-      if (roomId !== this.controlRoomId) return;
-
       // Only handle text messages
       if (event.content.msgtype !== "m.text") return;
 
-      // Parse message into ChatMessage format
-      const chatMessage: ChatMessage = {
-        id: event.event_id,
-        channelId: roomId,
-        authorId: event.sender,
-        authorName: event.sender,
-        content: event.content.body,
-        timestamp: new Date(event.origin_server_ts),
-        ...(event.content["m.relates_to"]?.rel_type === "m.thread" && {
-          threadId: event.content["m.relates_to"].event_id,
-        }),
-      };
-
-      // Parse command
-      const command = this.parseCommand(chatMessage);
-      if (command) {
-        void this.handleCommand(command);
-      }
+      void this.handleRoomMessage(roomId, event);
     });
 
     this.client.on("room.event", (_roomId: string, event: MatrixRoomEvent | null) => {
@@ -149,6 +142,114 @@ export class MatrixService implements IChatProvider {
     });
   }
 
+  /**
+   * Handle an incoming room message.
+   *
+   * Resolves the workspace for the room (via MatrixRoomService or fallback
+   * to the control room), then delegates to the shared CommandParserService
+   * for platform-agnostic command parsing and dispatches the result.
+   */
+  private async handleRoomMessage(roomId: string, event: MatrixRoomEvent): Promise<void> {
+    // Resolve workspace: try MatrixRoomService first, fall back to control room
+    let resolvedWorkspaceId: string | null = null;
+
+    if (this.matrixRoomService) {
+      resolvedWorkspaceId = await this.matrixRoomService.getWorkspaceForRoom(roomId);
+    }
+
+    // Fallback: if the room is the configured control room, use the env workspace
+    if (!resolvedWorkspaceId && roomId === this.controlRoomId) {
+      resolvedWorkspaceId = this.workspaceId;
+    }
+
+    // If room is not mapped to any workspace, ignore the message
+    if (!resolvedWorkspaceId) {
+      return;
+    }
+
+    const messageContent = event.content.body;
+
+    // Build ChatMessage for interface compatibility
+    const chatMessage: ChatMessage = {
+      id: event.event_id,
+      channelId: roomId,
+      authorId: event.sender,
+      authorName: event.sender,
+      content: messageContent,
+      timestamp: new Date(event.origin_server_ts),
+      ...(event.content["m.relates_to"]?.rel_type === "m.thread" && {
+        threadId: event.content["m.relates_to"].event_id,
+      }),
+    };
+
+    // Use shared CommandParserService if available
+    if (this.commandParser) {
+      // Normalize !mosaic to @mosaic for the shared parser
+      const normalizedContent = messageContent.replace(/^!mosaic/i, "@mosaic");
+
+      const result = this.commandParser.parseCommand(normalizedContent);
+
+      if (result.success) {
+        await this.handleParsedCommand(result.command, chatMessage, resolvedWorkspaceId);
+      } else if (normalizedContent.toLowerCase().startsWith("@mosaic")) {
+        // The user tried to use a command but it failed to parse -- send help
+        await this.sendMessage(roomId, result.error.help ?? result.error.message);
+      }
+      return;
+    }
+
+    // Fallback: use the built-in parseCommand if CommandParserService not injected
+    const command = this.parseCommand(chatMessage);
+    if (command) {
+      await this.handleCommand(command);
+    }
+  }
+
+  /**
+   * Handle a command parsed by the shared CommandParserService.
+   *
+   * Routes the ParsedCommand to the appropriate handler, passing
+   * along workspace context for job dispatch.
+   */
+  private async handleParsedCommand(
+    parsed: ParsedCommand,
+    message: ChatMessage,
+    workspaceId: string
+  ): Promise<void> {
+    this.logger.log(
+      `Handling command: ${parsed.action} from ${message.authorName} in workspace ${workspaceId}`
+    );
+
+    switch (parsed.action) {
+      case CommandAction.FIX:
+        await this.handleFixCommand(parsed.rawArgs, message, workspaceId);
+        break;
+      case CommandAction.STATUS:
+        await this.handleStatusCommand(parsed.rawArgs, message);
+        break;
+      case CommandAction.CANCEL:
+        await this.handleCancelCommand(parsed.rawArgs, message);
+        break;
+      case CommandAction.VERBOSE:
+        await this.handleVerboseCommand(parsed.rawArgs, message);
+        break;
+      case CommandAction.QUIET:
+        await this.handleQuietCommand(parsed.rawArgs, message);
+        break;
+      case CommandAction.HELP:
+        await this.handleHelpCommand(parsed.rawArgs, message);
+        break;
+      case CommandAction.RETRY:
+        await this.handleRetryCommand(parsed.rawArgs, message);
+        break;
+      default:
+        await this.sendMessage(
+          message.channelId,
+          `Unknown command. Type \`@mosaic help\` or \`!mosaic help\` for available commands.`
+        );
+    }
+  }
+
   /**
    * Disconnect from Matrix
    */
@@ -241,18 +342,35 @@ export class MatrixService implements IChatProvider {
   }
 
   /**
-   * Parse a command from a message
+   * Parse a command from a message (IChatProvider interface).
+   *
+   * Delegates to the shared CommandParserService when available,
+   * falling back to built-in parsing for backwards compatibility.
    */
   parseCommand(message: ChatMessage): ChatCommand | null {
     const { content } = message;
 
-    // Check if message mentions @mosaic or uses !mosaic prefix
+    // Try shared parser first
+    if (this.commandParser) {
+      const normalizedContent = content.replace(/^!mosaic/i, "@mosaic");
+      const result = this.commandParser.parseCommand(normalizedContent);
+
+      if (result.success) {
+        return {
+          command: result.command.action,
+          args: result.command.rawArgs,
+          message,
+        };
+      }
+      return null;
+    }
+
+    // Fallback: built-in parsing for when CommandParserService is not injected
     const lowerContent = content.toLowerCase();
     if (!lowerContent.includes("@mosaic") && !lowerContent.includes("!mosaic")) {
       return null;
     }
 
-    // Extract command and arguments
     const parts = content.trim().split(/\s+/);
     const mosaicIndex = parts.findIndex(
       (part) => part.toLowerCase().includes("@mosaic") || part.toLowerCase().includes("!mosaic")
@@ -270,7 +388,6 @@ export class MatrixService implements IChatProvider {
     const command = commandPart.toLowerCase();
     const args = parts.slice(mosaicIndex + 2);
 
-    // Valid commands
     const validCommands = ["fix", "status", "cancel", "verbose", "quiet", "help"];
 
     if (!validCommands.includes(command)) {
@@ -285,7 +402,7 @@ export class MatrixService implements IChatProvider {
   }
 
   /**
-   * Handle a parsed command
+   * Handle a parsed command (ChatCommand format, used by fallback path)
    */
   async handleCommand(command: ChatCommand): Promise<void> {
     const { command: cmd, args, message } = command;
@@ -296,7 +413,7 @@ export class MatrixService implements IChatProvider {
 
     switch (cmd) {
       case "fix":
-        await this.handleFixCommand(args, message);
+        await this.handleFixCommand(args, message, this.workspaceId);
         break;
       case "status":
         await this.handleStatusCommand(args, message);
@@ -324,7 +441,11 @@ export class MatrixService implements IChatProvider {
   /**
    * Handle fix command - Start a job for an issue
    */
-  private async handleFixCommand(args: string[], message: ChatMessage): Promise<void> {
+  private async handleFixCommand(
+    args: string[],
+    message: ChatMessage,
+    workspaceId?: string
+  ): Promise<void> {
     if (args.length === 0 || !args[0]) {
       await this.sendMessage(
         message.channelId,
@@ -333,7 +454,9 @@ export class MatrixService implements IChatProvider {
       return;
     }
 
-    const issueNumber = parseInt(args[0], 10);
+    // Parse issue number: handle both "#42" and "42" formats
+    const issueArg = args[0].replace(/^#/, "");
+    const issueNumber = parseInt(issueArg, 10);
 
     if (isNaN(issueNumber)) {
       await this.sendMessage(
@@ -343,6 +466,8 @@ export class MatrixService implements IChatProvider {
       return;
     }
 
+    const targetWorkspaceId = workspaceId ?? this.workspaceId;
+
     // Create thread for job updates
     const threadId = await this.createThread({
       channelId: message.channelId,
@@ -352,7 +477,7 @@ export class MatrixService implements IChatProvider {
 
     // Dispatch job to stitcher
     const result = await this.stitcherService.dispatchJob({
-      workspaceId: this.workspaceId,
+      workspaceId: targetWorkspaceId,
       type: "code-task",
       priority: 10,
       metadata: {
@@ -414,6 +539,27 @@ export class MatrixService implements IChatProvider {
     );
   }
 
+  /**
+   * Handle retry command - Retry a failed job
+   */
+  private async handleRetryCommand(args: string[], message: ChatMessage): Promise<void> {
+    if (args.length === 0 || !args[0]) {
+      await this.sendMessage(
+        message.channelId,
+        "Usage: `@mosaic retry <job-id>` or `!mosaic retry <job-id>`"
+      );
+      return;
+    }
+
+    const jobId = args[0];
+
+    // TODO: Implement job retry in stitcher
+    await this.sendMessage(
+      message.channelId,
+      `Retry command not yet implemented for job: ${jobId}`
+    );
+  }
+
   /**
    * Handle verbose command - Stream full logs to thread
    */
@@ -453,6 +599,7 @@ export class MatrixService implements IChatProvider {
 \`@mosaic fix <issue>\` or \`!mosaic fix <issue>\` - Start job for issue
 \`@mosaic status <job>\` or \`!mosaic status <job>\` - Get job status
 \`@mosaic cancel <job>\` or \`!mosaic cancel <job>\` - Cancel running job
+\`@mosaic retry <job>\` or \`!mosaic retry <job>\` - Retry failed job
 \`@mosaic verbose <job>\` or \`!mosaic verbose <job>\` - Stream full logs to thread
 \`@mosaic quiet\` or \`!mosaic quiet\` - Reduce notifications
 \`@mosaic help\` or \`!mosaic help\` - Show this help message