feat(orchestrator): add mission control proxy api

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

.env.example

@@ -343,6 +343,11 @@ RATE_LIMIT_STORAGE=redis
 # DISCORD_CONTROL_CHANNEL_ID=channel-id-for-commands
 # DISCORD_WORKSPACE_ID=your-workspace-uuid
 #
+# Agent channel routing: Maps Discord channels to specific agents.
+# Format: <channelId>:<agentName>,<channelId>:<agentName>
+# Example: 123456789:jarvis,987654321:builder
+# DISCORD_AGENT_CHANNELS=
+#
 # SECURITY: DISCORD_WORKSPACE_ID must be a valid workspace UUID from your database.
 # All Discord commands will execute within this workspace context for proper
 # multi-tenant isolation. Each Discord bot instance should be configured for

apps/api/prisma/migrations/20260307004007_ms23_mission_control_schema/migration.sql

@@ -0,0 +1,83 @@
+-- CreateTable
+CREATE TABLE "AgentConversationMessage" (
+    "id" TEXT NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "provider" TEXT NOT NULL DEFAULT 'internal',
+    "role" TEXT NOT NULL,
+    "content" TEXT NOT NULL,
+    "timestamp" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+
+    CONSTRAINT "AgentConversationMessage_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "AgentSessionTree" (
+    "id" TEXT NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "parentSessionId" TEXT,
+    "provider" TEXT NOT NULL DEFAULT 'internal',
+    "missionId" TEXT,
+    "taskId" TEXT,
+    "taskSource" TEXT DEFAULT 'internal',
+    "agentType" TEXT,
+    "status" TEXT NOT NULL DEFAULT 'spawning',
+    "spawnedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "completedAt" TIMESTAMP(3),
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+
+    CONSTRAINT "AgentSessionTree_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "AgentProviderConfig" (
+    "id" TEXT NOT NULL,
+    "workspaceId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "gatewayUrl" TEXT NOT NULL,
+    "credentials" JSONB NOT NULL DEFAULT '{}',
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AgentProviderConfig_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "OperatorAuditLog" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "action" TEXT NOT NULL,
+    "content" TEXT,
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "OperatorAuditLog_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "AgentConversationMessage_sessionId_timestamp_idx" ON "AgentConversationMessage"("sessionId", "timestamp");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AgentSessionTree_sessionId_key" ON "AgentSessionTree"("sessionId");
+
+-- CreateIndex
+CREATE INDEX "AgentSessionTree_parentSessionId_idx" ON "AgentSessionTree"("parentSessionId");
+
+-- CreateIndex
+CREATE INDEX "AgentSessionTree_missionId_idx" ON "AgentSessionTree"("missionId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "AgentProviderConfig_workspaceId_name_key" ON "AgentProviderConfig"("workspaceId", "name");
+
+-- CreateIndex
+CREATE INDEX "OperatorAuditLog_sessionId_idx" ON "OperatorAuditLog"("sessionId");
+
+-- CreateIndex
+CREATE INDEX "OperatorAuditLog_userId_idx" ON "OperatorAuditLog"("userId");
+
+-- CreateIndex
+CREATE INDEX "OperatorAuditLog_createdAt_idx" ON "OperatorAuditLog"("createdAt");

apps/api/prisma/schema.prisma

@@ -1739,3 +1739,66 @@ model UserAgent {
   @@unique([userId, name])
   @@index([userId])
 }
+
+// MS23: Agent conversation messages for Mission Control streaming
+model AgentConversationMessage {
+  id        String   @id @default(cuid())
+  sessionId String
+  provider  String   @default("internal")
+  role      String
+  content   String
+  timestamp DateTime @default(now())
+  metadata  Json     @default("{}")
+
+  @@index([sessionId, timestamp])
+}
+
+// MS23: Agent session tree for parent/child relationships
+model AgentSessionTree {
+  id              String   @id @default(cuid())
+  sessionId       String   @unique
+  parentSessionId String?
+  provider        String   @default("internal")
+  missionId       String?
+  taskId          String?
+  taskSource      String?  @default("internal")
+  agentType       String?
+  status          String   @default("spawning")
+  spawnedAt       DateTime @default(now())
+  completedAt     DateTime?
+  metadata        Json     @default("{}")
+
+  @@index([parentSessionId])
+  @@index([missionId])
+}
+
+// MS23: External agent provider configuration per workspace
+model AgentProviderConfig {
+  id          String   @id @default(cuid())
+  workspaceId String
+  name        String
+  provider    String
+  gatewayUrl  String
+  credentials Json     @default("{}")
+  isActive    Boolean  @default(true)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@unique([workspaceId, name])
+}
+
+// MS23: Audit log for operator interventions
+model OperatorAuditLog {
+  id        String   @id @default(cuid())
+  userId    String
+  sessionId String
+  provider  String
+  action    String
+  content   String?
+  metadata  Json     @default("{}")
+  createdAt DateTime @default(now())
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([createdAt])
+}

apps/api/src/agent-template/agent-template.module.ts

@@ -2,9 +2,10 @@ import { Module } from "@nestjs/common";
 import { AgentTemplateService } from "./agent-template.service";
 import { AgentTemplateController } from "./agent-template.controller";
 import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
 
 @Module({
-  imports: [PrismaModule],
+  imports: [PrismaModule, AuthModule],
   controllers: [AgentTemplateController],
   providers: [AgentTemplateService],
   exports: [AgentTemplateService],

apps/api/src/bridge/bridge.module.spec.ts

@@ -5,6 +5,7 @@ import { MatrixService } from "./matrix/matrix.service";
 import { StitcherService } from "../stitcher/stitcher.service";
 import { PrismaService } from "../prisma/prisma.service";
 import { BullMqService } from "../bullmq/bullmq.service";
+import { ChatProxyService } from "../chat-proxy/chat-proxy.service";
 import { CHAT_PROVIDERS } from "./bridge.constants";
 import type { IChatProvider } from "./interfaces";
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
@@ -89,6 +90,7 @@ interface SavedEnvVars {
   MATRIX_CONTROL_ROOM_ID?: string;
   MATRIX_WORKSPACE_ID?: string;
   ENCRYPTION_KEY?: string;
+  MOSAIC_SECRET_KEY?: string;
 }
 
 describe("BridgeModule", () => {
@@ -106,6 +108,7 @@ describe("BridgeModule", () => {
       MATRIX_CONTROL_ROOM_ID: process.env.MATRIX_CONTROL_ROOM_ID,
       MATRIX_WORKSPACE_ID: process.env.MATRIX_WORKSPACE_ID,
       ENCRYPTION_KEY: process.env.ENCRYPTION_KEY,
+      MOSAIC_SECRET_KEY: process.env.MOSAIC_SECRET_KEY,
     };
 
     // Clear all bridge env vars
@@ -120,6 +123,8 @@ describe("BridgeModule", () => {
 
     // Set encryption key (needed by StitcherService)
     process.env.ENCRYPTION_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    // Set MOSAIC_SECRET_KEY (needed by CryptoService via ChatProxyModule)
+    process.env.MOSAIC_SECRET_KEY = "test-mosaic-secret-key-minimum-32-characters-long";
 
     // Clear ready callbacks
     mockReadyCallbacks.length = 0;
@@ -149,6 +154,10 @@ describe("BridgeModule", () => {
       .useValue({})
       .overrideProvider(BullMqService)
       .useValue({})
+      .overrideProvider(ChatProxyService)
+      .useValue({
+        proxyChat: vi.fn().mockResolvedValue(new Response()),
+      })
       .compile();
   }
 

apps/api/src/bridge/bridge.module.ts

@@ -5,6 +5,8 @@ import { MatrixRoomService } from "./matrix/matrix-room.service";
 import { MatrixStreamingService } from "./matrix/matrix-streaming.service";
 import { CommandParserService } from "./parser/command-parser.service";
 import { StitcherModule } from "../stitcher/stitcher.module";
+import { ChatProxyModule } from "../chat-proxy/chat-proxy.module";
+import { PrismaModule } from "../prisma/prisma.module";
 import { CHAT_PROVIDERS } from "./bridge.constants";
 import type { IChatProvider } from "./interfaces";
 
@@ -28,7 +30,7 @@ const logger = new Logger("BridgeModule");
  * MatrixRoomService handles workspace-to-Matrix-room mapping.
  */
 @Module({
-  imports: [StitcherModule],
+  imports: [StitcherModule, ChatProxyModule, PrismaModule],
   providers: [
     CommandParserService,
     MatrixRoomService,

apps/api/src/bridge/discord/discord.service.spec.ts

@@ -1,6 +1,8 @@
 import { Test, TestingModule } from "@nestjs/testing";
 import { DiscordService } from "./discord.service";
 import { StitcherService } from "../../stitcher/stitcher.service";
+import { ChatProxyService } from "../../chat-proxy/chat-proxy.service";
+import { PrismaService } from "../../prisma/prisma.service";
 import { Client, Events, GatewayIntentBits, Message } from "discord.js";
 import { vi, describe, it, expect, beforeEach } from "vitest";
 import type { ChatMessage, ChatCommand } from "../interfaces";
@@ -61,6 +63,8 @@ vi.mock("discord.js", () => {
 describe("DiscordService", () => {
   let service: DiscordService;
   let stitcherService: StitcherService;
+  let chatProxyService: ChatProxyService;
+  let prismaService: PrismaService;
 
   const mockStitcherService = {
     dispatchJob: vi.fn().mockResolvedValue({
@@ -71,12 +75,29 @@ describe("DiscordService", () => {
     trackJobEvent: vi.fn().mockResolvedValue(undefined),
   };
 
+  const mockChatProxyService = {
+    proxyChat: vi.fn().mockResolvedValue(
+      new Response('data: {"choices":[{"delta":{"content":"Hello"}}]}\n\ndata: [DONE]\n\n', {
+        headers: { "Content-Type": "text/event-stream" },
+      })
+    ),
+  };
+
+  const mockPrismaService = {
+    workspace: {
+      findUnique: vi.fn().mockResolvedValue({
+        ownerId: "owner-user-id",
+      }),
+    },
+  };
+
   beforeEach(async () => {
     // Set environment variables for testing
     process.env.DISCORD_BOT_TOKEN = "test-token";
     process.env.DISCORD_GUILD_ID = "test-guild-id";
     process.env.DISCORD_CONTROL_CHANNEL_ID = "test-channel-id";
     process.env.DISCORD_WORKSPACE_ID = "test-workspace-id";
+    process.env.DISCORD_AGENT_CHANNELS = "jarvis-channel:jarvis,builder-channel:builder";
 
     // Clear callbacks
     mockReadyCallbacks.length = 0;
@@ -89,11 +110,21 @@ describe("DiscordService", () => {
           provide: StitcherService,
           useValue: mockStitcherService,
         },
+        {
+          provide: ChatProxyService,
+          useValue: mockChatProxyService,
+        },
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
       ],
     }).compile();
 
     service = module.get<DiscordService>(DiscordService);
     stitcherService = module.get<StitcherService>(StitcherService);
+    chatProxyService = module.get<ChatProxyService>(ChatProxyService);
+    prismaService = module.get<PrismaService>(PrismaService);
 
     // Clear all mocks
     vi.clearAllMocks();
@@ -449,6 +480,14 @@ describe("DiscordService", () => {
             provide: StitcherService,
             useValue: mockStitcherService,
           },
+          {
+            provide: ChatProxyService,
+            useValue: mockChatProxyService,
+          },
+          {
+            provide: PrismaService,
+            useValue: mockPrismaService,
+          },
         ],
       }).compile();
 
@@ -470,6 +509,14 @@ describe("DiscordService", () => {
             provide: StitcherService,
             useValue: mockStitcherService,
           },
+          {
+            provide: ChatProxyService,
+            useValue: mockChatProxyService,
+          },
+          {
+            provide: PrismaService,
+            useValue: mockPrismaService,
+          },
         ],
       }).compile();
 
@@ -492,6 +539,14 @@ describe("DiscordService", () => {
             provide: StitcherService,
             useValue: mockStitcherService,
           },
+          {
+            provide: ChatProxyService,
+            useValue: mockChatProxyService,
+          },
+          {
+            provide: PrismaService,
+            useValue: mockPrismaService,
+          },
         ],
       }).compile();
 
@@ -654,4 +709,150 @@ describe("DiscordService", () => {
       expect(loggedError.statusCode).toBe(408);
     });
   });
+
+  describe("Agent Channel Routing", () => {
+    it("should load agent channel mappings from environment", () => {
+      // The service should have loaded the agent channels from DISCORD_AGENT_CHANNELS
+      expect((service as any).agentChannels.size).toBe(2);
+      expect((service as any).agentChannels.get("jarvis-channel")).toBe("jarvis");
+      expect((service as any).agentChannels.get("builder-channel")).toBe("builder");
+    });
+
+    it("should handle empty agent channels config", async () => {
+      delete process.env.DISCORD_AGENT_CHANNELS;
+
+      const module: TestingModule = await Test.createTestingModule({
+        providers: [
+          DiscordService,
+          {
+            provide: StitcherService,
+            useValue: mockStitcherService,
+          },
+          {
+            provide: ChatProxyService,
+            useValue: mockChatProxyService,
+          },
+          {
+            provide: PrismaService,
+            useValue: mockPrismaService,
+          },
+        ],
+      }).compile();
+
+      const newService = module.get<DiscordService>(DiscordService);
+      expect((newService as any).agentChannels.size).toBe(0);
+
+      // Restore for other tests
+      process.env.DISCORD_AGENT_CHANNELS = "jarvis-channel:jarvis,builder-channel:builder";
+    });
+
+    it("should route messages in agent channels to ChatProxyService", async () => {
+      const mockChannel = {
+        send: vi.fn().mockResolvedValue({}),
+        isTextBased: () => true,
+        sendTyping: vi.fn(),
+      };
+      (mockClient.channels.fetch as any).mockResolvedValue(mockChannel);
+
+      // Create a mock streaming response
+      const mockStreamResponse = new Response(
+        'data: {"choices":[{"delta":{"content":"Test response"}}]}\n\ndata: [DONE]\n\n',
+        { headers: { "Content-Type": "text/event-stream" } }
+      );
+      mockChatProxyService.proxyChat.mockResolvedValue(mockStreamResponse);
+
+      await service.connect();
+
+      // Simulate a message in the jarvis channel
+      const message: ChatMessage = {
+        id: "msg-agent-1",
+        channelId: "jarvis-channel",
+        authorId: "user-1",
+        authorName: "TestUser",
+        content: "Hello Jarvis!",
+        timestamp: new Date(),
+      };
+
+      // Call handleAgentChat directly
+      await (service as any).handleAgentChat(message, "jarvis");
+
+      // Verify ChatProxyService was called with workspace owner's ID and agent name
+      expect(mockChatProxyService.proxyChat).toHaveBeenCalledWith(
+        "owner-user-id",
+        [{ role: "user", content: "Hello Jarvis!" }],
+        undefined,
+        "jarvis"
+      );
+
+      // Verify response was sent to channel
+      expect(mockChannel.send).toHaveBeenCalled();
+    });
+
+    it("should not route empty messages", async () => {
+      const message: ChatMessage = {
+        id: "msg-empty",
+        channelId: "jarvis-channel",
+        authorId: "user-1",
+        authorName: "TestUser",
+        content: "   ",
+        timestamp: new Date(),
+      };
+
+      await (service as any).handleAgentChat(message, "jarvis");
+
+      expect(mockChatProxyService.proxyChat).not.toHaveBeenCalled();
+    });
+
+    it("should handle ChatProxyService errors gracefully", async () => {
+      const mockChannel = {
+        send: vi.fn().mockResolvedValue({}),
+        isTextBased: () => true,
+        sendTyping: vi.fn(),
+      };
+      (mockClient.channels.fetch as any).mockResolvedValue(mockChannel);
+
+      mockChatProxyService.proxyChat.mockRejectedValue(new Error("Agent not found"));
+
+      await service.connect();
+
+      const message: ChatMessage = {
+        id: "msg-error",
+        channelId: "jarvis-channel",
+        authorId: "user-1",
+        authorName: "TestUser",
+        content: "Hello",
+        timestamp: new Date(),
+      };
+
+      await (service as any).handleAgentChat(message, "jarvis");
+
+      // Should send error message to channel
+      expect(mockChannel.send).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to get response from jarvis")
+      );
+    });
+
+    it("should split long messages for Discord", () => {
+      const longContent = "A".repeat(5000);
+      const chunks = (service as any).splitMessageForDiscord(longContent);
+
+      // Should split into chunks of 2000 or less
+      expect(chunks.length).toBeGreaterThan(1);
+      for (const chunk of chunks) {
+        expect(chunk.length).toBeLessThanOrEqual(2000);
+      }
+
+      // Reassembled content should match original
+      expect(chunks.join("")).toBe(longContent.trim());
+    });
+
+    it("should prefer paragraph breaks when splitting messages", () => {
+      const content = "A".repeat(1500) + "\n\n" + "B".repeat(1500);
+      const chunks = (service as any).splitMessageForDiscord(content);
+
+      expect(chunks.length).toBe(2);
+      expect(chunks[0]).toContain("A");
+      expect(chunks[1]).toContain("B");
+    });
+  });
 });

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

@@ -1,6 +1,8 @@
 import { Injectable, Logger } from "@nestjs/common";
 import { Client, Events, GatewayIntentBits, TextChannel, ThreadChannel } from "discord.js";
 import { StitcherService } from "../../stitcher/stitcher.service";
+import { ChatProxyService } from "../../chat-proxy/chat-proxy.service";
+import { PrismaService } from "../../prisma/prisma.service";
 import { sanitizeForLogging } from "../../common/utils";
 import type {
   IChatProvider,
@@ -17,6 +19,7 @@ import type {
  * - Connect to Discord via bot token
  * - Listen for commands in designated channels
  * - Forward commands to stitcher
+ * - Route messages in agent channels to specific agents via ChatProxyService
  * - Receive status updates from herald
  * - Post updates to threads
  */
@@ -28,12 +31,21 @@ export class DiscordService implements IChatProvider {
   private readonly botToken: string;
   private readonly controlChannelId: string;
   private readonly workspaceId: string;
+  private readonly agentChannels = new Map<string, string>();
+  private workspaceOwnerId: string | null = null;
 
-  constructor(private readonly stitcherService: StitcherService) {
+  constructor(
+    private readonly stitcherService: StitcherService,
+    private readonly chatProxyService: ChatProxyService,
+    private readonly prisma: PrismaService
+  ) {
     this.botToken = process.env.DISCORD_BOT_TOKEN ?? "";
     this.controlChannelId = process.env.DISCORD_CONTROL_CHANNEL_ID ?? "";
     this.workspaceId = process.env.DISCORD_WORKSPACE_ID ?? "";
 
+    // Load agent channel mappings from environment
+    this.loadAgentChannels();
+
     // Initialize Discord client with required intents
     this.client = new Client({
       intents: [
@@ -46,6 +58,51 @@ export class DiscordService implements IChatProvider {
     this.setupEventHandlers();
   }
 
+  /**
+   * Load agent channel mappings from environment variables.
+   * Format: DISCORD_AGENT_CHANNELS=<channelId>:<agentName>,<channelId>:<agentName>
+   * Example: DISCORD_AGENT_CHANNELS=123456:jarvis,789012:builder
+   */
+  private loadAgentChannels(): void {
+    const channelsConfig = process.env.DISCORD_AGENT_CHANNELS ?? "";
+    if (!channelsConfig) {
+      this.logger.debug("No agent channels configured (DISCORD_AGENT_CHANNELS not set)");
+      return;
+    }
+
+    const channels = channelsConfig.split(",").map((pair) => pair.trim());
+    for (const channel of channels) {
+      const [channelId, agentName] = channel.split(":");
+      if (channelId && agentName) {
+        this.agentChannels.set(channelId.trim(), agentName.trim());
+        this.logger.log(`Agent channel mapped: ${channelId.trim()} → ${agentName.trim()}`);
+      }
+    }
+  }
+
+  /**
+   * Get the workspace owner's user ID for chat proxy routing.
+   * Caches the result after first lookup.
+   */
+  private async getWorkspaceOwnerId(): Promise<string> {
+    if (this.workspaceOwnerId) {
+      return this.workspaceOwnerId;
+    }
+
+    const workspace = await this.prisma.workspace.findUnique({
+      where: { id: this.workspaceId },
+      select: { ownerId: true },
+    });
+
+    if (!workspace) {
+      throw new Error(`Workspace not found: ${this.workspaceId}`);
+    }
+
+    this.workspaceOwnerId = workspace.ownerId;
+    this.logger.debug(`Workspace owner resolved: ${workspace.ownerId}`);
+    return workspace.ownerId;
+  }
+
   /**
    * Setup event handlers for Discord client
    */
@@ -60,9 +117,6 @@ export class DiscordService implements IChatProvider {
       // Ignore bot messages
       if (message.author.bot) return;
 
-      // Check if message is in control channel
-      if (message.channelId !== this.controlChannelId) return;
-
       // Parse message into ChatMessage format
       const chatMessage: ChatMessage = {
         id: message.id,
@@ -74,6 +128,16 @@ export class DiscordService implements IChatProvider {
         ...(message.channel.isThread() && { threadId: message.channelId }),
       };
 
+      // Check if message is in an agent channel
+      const agentName = this.agentChannels.get(message.channelId);
+      if (agentName) {
+        void this.handleAgentChat(chatMessage, agentName);
+        return;
+      }
+
+      // Check if message is in control channel for commands
+      if (message.channelId !== this.controlChannelId) return;
+
       // Parse command
       const command = this.parseCommand(chatMessage);
       if (command) {
@@ -394,4 +458,150 @@ export class DiscordService implements IChatProvider {
 
     await this.sendMessage(message.channelId, helpMessage);
   }
+
+  /**
+   * Handle agent chat - Route message to specific agent via ChatProxyService
+   * Messages in agent channels are sent directly to the agent without requiring @mosaic prefix.
+   */
+  private async handleAgentChat(message: ChatMessage, agentName: string): Promise<void> {
+    this.logger.log(
+      `Routing message from ${message.authorName} to agent "${agentName}" in channel ${message.channelId}`
+    );
+
+    // Ignore empty messages
+    if (!message.content.trim()) {
+      return;
+    }
+
+    try {
+      // Get workspace owner ID for routing
+      const userId = await this.getWorkspaceOwnerId();
+
+      // Build message history (just the user's message for now)
+      const messages = [{ role: "user" as const, content: message.content }];
+
+      // Send typing indicator while waiting for response
+      const channel = await this.client.channels.fetch(message.channelId);
+      if (channel?.isTextBased()) {
+        void (channel as TextChannel).sendTyping();
+      }
+
+      // Proxy to agent
+      const response = await this.chatProxyService.proxyChat(
+        userId,
+        messages,
+        undefined,
+        agentName
+      );
+
+      // Stream the response to channel
+      await this.streamResponseToChannel(message.channelId, response);
+
+      this.logger.debug(`Agent "${agentName}" response sent to channel ${message.channelId}`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Failed to route message to agent "${agentName}": ${errorMessage}`);
+      await this.sendMessage(
+        message.channelId,
+        `Failed to get response from ${agentName}. Please try again later.`
+      );
+    }
+  }
+
+  /**
+   * Stream SSE response from chat proxy and send to Discord channel.
+   * Collects the full response and sends as a single message for reliability.
+   */
+  private async streamResponseToChannel(channelId: string, response: Response): Promise<string> {
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new Error("Response body is not readable");
+    }
+
+    const decoder = new TextDecoder();
+    let fullContent = "";
+    let buffer = "";
+
+    try {
+      let readResult = await reader.read();
+      while (!readResult.done) {
+        const { value } = readResult;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data = line.slice(6);
+            if (data === "[DONE]") continue;
+
+            try {
+              const parsed = JSON.parse(data) as {
+                choices?: { delta?: { content?: string } }[];
+              };
+              const content = parsed.choices?.[0]?.delta?.content;
+              if (content) {
+                fullContent += content;
+              }
+            } catch {
+              // Skip invalid JSON
+            }
+          }
+        }
+        readResult = await reader.read();
+      }
+
+      // Send the full response to Discord
+      if (fullContent.trim()) {
+        // Discord has a 2000 character limit, split if needed
+        const chunks = this.splitMessageForDiscord(fullContent);
+        for (const chunk of chunks) {
+          await this.sendMessage(channelId, chunk);
+        }
+      }
+
+      return fullContent;
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /**
+   * Split a message into chunks that fit within Discord's 2000 character limit.
+   * Tries to split on paragraph or sentence boundaries when possible.
+   */
+  private splitMessageForDiscord(content: string, maxLength = 2000): string[] {
+    if (content.length <= maxLength) {
+      return [content];
+    }
+
+    const chunks: string[] = [];
+    let remaining = content;
+
+    while (remaining.length > maxLength) {
+      // Try to find a good break point
+      let breakPoint = remaining.lastIndexOf("\n\n", maxLength);
+      if (breakPoint < maxLength * 0.5) {
+        breakPoint = remaining.lastIndexOf("\n", maxLength);
+      }
+      if (breakPoint < maxLength * 0.5) {
+        breakPoint = remaining.lastIndexOf(". ", maxLength);
+      }
+      if (breakPoint < maxLength * 0.5) {
+        breakPoint = remaining.lastIndexOf(" ", maxLength);
+      }
+      if (breakPoint < maxLength * 0.5) {
+        breakPoint = maxLength - 1;
+      }
+
+      chunks.push(remaining.slice(0, breakPoint + 1).trim());
+      remaining = remaining.slice(breakPoint + 1).trim();
+    }
+
+    if (remaining.length > 0) {
+      chunks.push(remaining);
+    }
+
+    return chunks;
+  }
 }

apps/api/src/bridge/matrix/matrix-bridge.integration.spec.ts

@@ -28,6 +28,7 @@ import { StitcherService } from "../../stitcher/stitcher.service";
 import { HeraldService } from "../../herald/herald.service";
 import { PrismaService } from "../../prisma/prisma.service";
 import { BullMqService } from "../../bullmq/bullmq.service";
+import { ChatProxyService } from "../../chat-proxy/chat-proxy.service";
 import type { IChatProvider } from "../interfaces";
 import { JOB_CREATED, JOB_STARTED } from "../../job-events/event-types";
 
@@ -192,6 +193,7 @@ function setDiscordEnv(): void {
 
 function setEncryptionKey(): void {
   process.env.ENCRYPTION_KEY = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+  process.env.MOSAIC_SECRET_KEY = "test-mosaic-secret-key-minimum-32-characters-long";
 }
 
 /**
@@ -205,6 +207,10 @@ async function compileBridgeModule(): Promise<TestingModule> {
     .useValue({})
     .overrideProvider(BullMqService)
     .useValue({})
+    .overrideProvider(ChatProxyService)
+    .useValue({
+      proxyChat: vi.fn().mockResolvedValue(new Response()),
+    })
     .compile();
 }
 

apps/api/src/chat-proxy/chat-proxy.service.spec.ts

@@ -1,4 +1,8 @@
-import { ServiceUnavailableException } from "@nestjs/common";
+import {
+  ServiceUnavailableException,
+  NotFoundException,
+  BadGatewayException,
+} from "@nestjs/common";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ChatProxyService } from "./chat-proxy.service";
 
@@ -9,6 +13,9 @@ describe("ChatProxyService", () => {
     userAgentConfig: {
       findUnique: vi.fn(),
     },
+    userAgent: {
+      findUnique: vi.fn(),
+    },
   };
 
   const containerLifecycle = {
@@ -16,13 +23,17 @@ describe("ChatProxyService", () => {
     touch: vi.fn(),
   };
 
+  const config = {
+    get: vi.fn(),
+  };
+
   let service: ChatProxyService;
   let fetchMock: ReturnType<typeof vi.fn>;
 
   beforeEach(() => {
     fetchMock = vi.fn();
     vi.stubGlobal("fetch", fetchMock);
-    service = new ChatProxyService(prisma as never, containerLifecycle as never);
+    service = new ChatProxyService(prisma as never, containerLifecycle as never, config as never);
   });
 
   afterEach(() => {
@@ -105,4 +116,135 @@ describe("ChatProxyService", () => {
       );
     });
   });
+
+  describe("proxyChat with agent routing", () => {
+    it("includes agent config when agentName is specified", async () => {
+      const mockAgent = {
+        name: "jarvis",
+        displayName: "Jarvis",
+        personality: "Capable, direct, proactive.",
+        primaryModel: "opus",
+        isActive: true,
+      };
+
+      containerLifecycle.ensureRunning.mockResolvedValue({
+        url: "http://mosaic-user-user-123:19000",
+        token: "gateway-token",
+      });
+      containerLifecycle.touch.mockResolvedValue(undefined);
+      prisma.userAgent.findUnique.mockResolvedValue(mockAgent);
+      fetchMock.mockResolvedValue(new Response("event: token\ndata: hello\n\n"));
+
+      const messages = [{ role: "user", content: "Hello Jarvis" }];
+      await service.proxyChat(userId, messages, undefined, "jarvis");
+
+      const [, request] = fetchMock.mock.calls[0] as [string, RequestInit];
+      const parsedBody = JSON.parse(String(request.body));
+
+      expect(parsedBody).toEqual({
+        messages,
+        model: "opus",
+        stream: true,
+        agent: "jarvis",
+        agent_personality: "Capable, direct, proactive.",
+      });
+    });
+
+    it("throws NotFoundException when agent not found", async () => {
+      containerLifecycle.ensureRunning.mockResolvedValue({
+        url: "http://mosaic-user-user-123:19000",
+        token: "gateway-token",
+      });
+      containerLifecycle.touch.mockResolvedValue(undefined);
+      prisma.userAgent.findUnique.mockResolvedValue(null);
+
+      const messages = [{ role: "user", content: "Hello" }];
+      await expect(service.proxyChat(userId, messages, undefined, "nonexistent")).rejects.toThrow(
+        NotFoundException
+      );
+    });
+
+    it("throws NotFoundException when agent is not active", async () => {
+      containerLifecycle.ensureRunning.mockResolvedValue({
+        url: "http://mosaic-user-user-123:19000",
+        token: "gateway-token",
+      });
+      containerLifecycle.touch.mockResolvedValue(undefined);
+      prisma.userAgent.findUnique.mockResolvedValue({
+        name: "inactive-agent",
+        displayName: "Inactive",
+        personality: "...",
+        primaryModel: null,
+        isActive: false,
+      });
+
+      const messages = [{ role: "user", content: "Hello" }];
+      await expect(
+        service.proxyChat(userId, messages, undefined, "inactive-agent")
+      ).rejects.toThrow(NotFoundException);
+    });
+
+    it("falls back to default model when agent has no primaryModel", async () => {
+      const mockAgent = {
+        name: "jarvis",
+        displayName: "Jarvis",
+        personality: "Capable, direct, proactive.",
+        primaryModel: null,
+        isActive: true,
+      };
+
+      containerLifecycle.ensureRunning.mockResolvedValue({
+        url: "http://mosaic-user-user-123:19000",
+        token: "gateway-token",
+      });
+      containerLifecycle.touch.mockResolvedValue(undefined);
+      prisma.userAgent.findUnique.mockResolvedValue(mockAgent);
+      prisma.userAgentConfig.findUnique.mockResolvedValue(null);
+      fetchMock.mockResolvedValue(new Response("event: token\ndata: hello\n\n"));
+
+      const messages = [{ role: "user", content: "Hello" }];
+      await service.proxyChat(userId, messages, undefined, "jarvis");
+
+      const [, request] = fetchMock.mock.calls[0] as [string, RequestInit];
+      const parsedBody = JSON.parse(String(request.body));
+
+      expect(parsedBody.model).toBe("openclaw:default");
+    });
+  });
+
+  describe("proxyGuestChat", () => {
+    it("uses environment variables for guest LLM configuration", async () => {
+      config.get.mockImplementation((key: string) => {
+        if (key === "GUEST_LLM_URL") return "http://10.1.1.42:11434/v1";
+        if (key === "GUEST_LLM_MODEL") return "llama3.2";
+        return undefined;
+      });
+      fetchMock.mockResolvedValue(new Response("event: token\ndata: hello\n\n"));
+
+      const messages = [{ role: "user", content: "Hello" }];
+      await service.proxyGuestChat(messages);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "http://10.1.1.42:11434/v1/chat/completions",
+        expect.objectContaining({
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+        })
+      );
+
+      const [, request] = fetchMock.mock.calls[0] as [string, RequestInit];
+      const parsedBody = JSON.parse(String(request.body));
+      expect(parsedBody.model).toBe("llama3.2");
+    });
+
+    it("throws BadGatewayException on guest LLM errors", async () => {
+      config.get.mockReturnValue(undefined);
+      fetchMock.mockResolvedValue(new Response("Internal Server Error", { status: 500 }));
+
+      const messages = [{ role: "user", content: "Hello" }];
+      await expect(service.proxyGuestChat(messages)).rejects.toThrow(BadGatewayException);
+    });
+  });
 });

apps/api/src/user-agent/user-agent.module.ts

@@ -2,9 +2,10 @@ import { Module } from "@nestjs/common";
 import { UserAgentService } from "./user-agent.service";
 import { UserAgentController } from "./user-agent.controller";
 import { PrismaModule } from "../prisma/prisma.module";
+import { AuthModule } from "../auth/auth.module";
 
 @Module({
-  imports: [PrismaModule],
+  imports: [PrismaModule, AuthModule],
   controllers: [UserAgentController],
   providers: [UserAgentService],
   exports: [UserAgentService],

apps/api/src/user-agent/user-agent.service.spec.ts

@@ -0,0 +1,300 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { UserAgentService } from "./user-agent.service";
+import { PrismaService } from "../prisma/prisma.service";
+import { NotFoundException, ConflictException, ForbiddenException } from "@nestjs/common";
+
+describe("UserAgentService", () => {
+  let service: UserAgentService;
+  let prisma: PrismaService;
+
+  const mockPrismaService = {
+    userAgent: {
+      findMany: vi.fn(),
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+    },
+    agentTemplate: {
+      findUnique: vi.fn(),
+    },
+  };
+
+  const mockUserId = "550e8400-e29b-41d4-a716-446655440001";
+  const mockAgentId = "550e8400-e29b-41d4-a716-446655440002";
+  const mockTemplateId = "550e8400-e29b-41d4-a716-446655440003";
+
+  const mockAgent = {
+    id: mockAgentId,
+    userId: mockUserId,
+    templateId: null,
+    name: "jarvis",
+    displayName: "Jarvis",
+    role: "orchestrator",
+    personality: "Capable, direct, proactive.",
+    primaryModel: "opus",
+    fallbackModels: ["sonnet"],
+    toolPermissions: ["all"],
+    discordChannel: "jarvis",
+    isActive: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  const mockTemplate = {
+    id: mockTemplateId,
+    name: "builder",
+    displayName: "Builder",
+    role: "coding",
+    personality: "Focused, thorough.",
+    primaryModel: "codex",
+    fallbackModels: ["sonnet"],
+    toolPermissions: ["exec", "read", "write"],
+    discordChannel: "builder",
+    isActive: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UserAgentService,
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<UserAgentService>(UserAgentService);
+    prisma = module.get<PrismaService>(PrismaService);
+
+    vi.clearAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(service).toBeDefined();
+  });
+
+  describe("findAll", () => {
+    it("should return all agents for a user", async () => {
+      mockPrismaService.userAgent.findMany.mockResolvedValue([mockAgent]);
+
+      const result = await service.findAll(mockUserId);
+
+      expect(result).toEqual([mockAgent]);
+      expect(mockPrismaService.userAgent.findMany).toHaveBeenCalledWith({
+        where: { userId: mockUserId },
+        orderBy: { createdAt: "asc" },
+      });
+    });
+
+    it("should return empty array if no agents", async () => {
+      mockPrismaService.userAgent.findMany.mockResolvedValue([]);
+
+      const result = await service.findAll(mockUserId);
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("findOne", () => {
+    it("should return an agent by id", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+
+      const result = await service.findOne(mockUserId, mockAgentId);
+
+      expect(result).toEqual(mockAgent);
+    });
+
+    it("should throw NotFoundException if agent not found", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(null);
+
+      await expect(service.findOne(mockUserId, mockAgentId)).rejects.toThrow(NotFoundException);
+    });
+
+    it("should throw ForbiddenException if agent belongs to different user", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue({
+        ...mockAgent,
+        userId: "different-user-id",
+      });
+
+      await expect(service.findOne(mockUserId, mockAgentId)).rejects.toThrow(ForbiddenException);
+    });
+  });
+
+  describe("findByName", () => {
+    it("should return an agent by name", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+
+      const result = await service.findByName(mockUserId, "jarvis");
+
+      expect(result).toEqual(mockAgent);
+      expect(mockPrismaService.userAgent.findUnique).toHaveBeenCalledWith({
+        where: { userId_name: { userId: mockUserId, name: "jarvis" } },
+      });
+    });
+
+    it("should throw NotFoundException if agent not found", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(null);
+
+      await expect(service.findByName(mockUserId, "nonexistent")).rejects.toThrow(
+        NotFoundException
+      );
+    });
+  });
+
+  describe("create", () => {
+    it("should create a new agent", async () => {
+      const createDto = {
+        name: "jarvis",
+        displayName: "Jarvis",
+        role: "orchestrator",
+        personality: "Capable, direct, proactive.",
+      };
+
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(null);
+      mockPrismaService.userAgent.create.mockResolvedValue(mockAgent);
+
+      const result = await service.create(mockUserId, createDto);
+
+      expect(result).toEqual(mockAgent);
+    });
+
+    it("should throw ConflictException if agent name already exists", async () => {
+      const createDto = {
+        name: "jarvis",
+        displayName: "Jarvis",
+        role: "orchestrator",
+        personality: "Capable, direct, proactive.",
+      };
+
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+
+      await expect(service.create(mockUserId, createDto)).rejects.toThrow(ConflictException);
+    });
+
+    it("should throw NotFoundException if templateId is invalid", async () => {
+      const createDto = {
+        name: "custom",
+        displayName: "Custom",
+        role: "custom",
+        personality: "Custom agent",
+        templateId: "nonexistent-template",
+      };
+
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(null);
+      mockPrismaService.agentTemplate.findUnique.mockResolvedValue(null);
+
+      await expect(service.create(mockUserId, createDto)).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe("createFromTemplate", () => {
+    it("should create an agent from a template", async () => {
+      mockPrismaService.agentTemplate.findUnique.mockResolvedValue(mockTemplate);
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(null);
+      mockPrismaService.userAgent.create.mockResolvedValue({
+        ...mockAgent,
+        templateId: mockTemplateId,
+        name: mockTemplate.name,
+        displayName: mockTemplate.displayName,
+        role: mockTemplate.role,
+      });
+
+      const result = await service.createFromTemplate(mockUserId, mockTemplateId);
+
+      expect(result.name).toBe(mockTemplate.name);
+      expect(result.displayName).toBe(mockTemplate.displayName);
+    });
+
+    it("should throw NotFoundException if template not found", async () => {
+      mockPrismaService.agentTemplate.findUnique.mockResolvedValue(null);
+
+      await expect(service.createFromTemplate(mockUserId, mockTemplateId)).rejects.toThrow(
+        NotFoundException
+      );
+    });
+
+    it("should throw ConflictException if agent name already exists", async () => {
+      mockPrismaService.agentTemplate.findUnique.mockResolvedValue(mockTemplate);
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+
+      await expect(service.createFromTemplate(mockUserId, mockTemplateId)).rejects.toThrow(
+        ConflictException
+      );
+    });
+  });
+
+  describe("update", () => {
+    it("should update an agent", async () => {
+      const updateDto = { displayName: "Updated Jarvis" };
+      const updatedAgent = { ...mockAgent, ...updateDto };
+
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+      mockPrismaService.userAgent.update.mockResolvedValue(updatedAgent);
+
+      const result = await service.update(mockUserId, mockAgentId, updateDto);
+
+      expect(result.displayName).toBe("Updated Jarvis");
+    });
+
+    it("should throw ConflictException if new name already exists", async () => {
+      const updateDto = { name: "existing-name" };
+
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+      // Second call checks for existing name
+      mockPrismaService.userAgent.findUnique.mockResolvedValue({ ...mockAgent, id: "other-id" });
+
+      await expect(service.update(mockUserId, mockAgentId, updateDto)).rejects.toThrow(
+        ConflictException
+      );
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete an agent", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+      mockPrismaService.userAgent.delete.mockResolvedValue(mockAgent);
+
+      const result = await service.remove(mockUserId, mockAgentId);
+
+      expect(result).toEqual(mockAgent);
+    });
+  });
+
+  describe("getStatus", () => {
+    it("should return agent status", async () => {
+      mockPrismaService.userAgent.findUnique.mockResolvedValue(mockAgent);
+
+      const result = await service.getStatus(mockUserId, mockAgentId);
+
+      expect(result).toEqual({
+        id: mockAgentId,
+        name: "jarvis",
+        displayName: "Jarvis",
+        role: "orchestrator",
+        isActive: true,
+      });
+    });
+  });
+
+  describe("getAllStatuses", () => {
+    it("should return all agent statuses", async () => {
+      mockPrismaService.userAgent.findMany.mockResolvedValue([mockAgent]);
+
+      const result = await service.getAllStatuses(mockUserId);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        id: mockAgentId,
+        name: "jarvis",
+        displayName: "Jarvis",
+        role: "orchestrator",
+        isActive: true,
+      });
+    });
+  });
+});

apps/orchestrator/Dockerfile

@@ -21,6 +21,7 @@ FROM base AS deps
 COPY packages/shared/package.json ./packages/shared/
 COPY packages/config/package.json ./packages/config/
 COPY apps/orchestrator/package.json ./apps/orchestrator/
+# API schema is available via apps/orchestrator/prisma/schema.prisma symlink
 
 # Copy npm configuration for native binary architecture hints
 COPY .npmrc ./
@@ -46,6 +47,15 @@ COPY --from=deps /app/packages/shared/node_modules ./packages/shared/node_module
 COPY --from=deps /app/packages/config/node_modules ./packages/config/node_modules
 COPY --from=deps /app/apps/orchestrator/node_modules ./apps/orchestrator/node_modules
 
+# The repo has apps/orchestrator/prisma/schema.prisma as a symlink for CI use.
+# Kaniko resolves destination symlinks on COPY, which fails because the symlink
+# target (../../api/prisma/schema.prisma) doesn't exist in the container.
+# Fix: remove the dangling symlink first, then copy the real schema file there.
+RUN rm -f apps/orchestrator/prisma/schema.prisma
+COPY apps/api/prisma/schema.prisma ./apps/orchestrator/prisma/schema.prisma
+# pnpm turbo build runs prisma:generate (--schema=./prisma/schema.prisma) from the
+# orchestrator package context — no cross-package project-root issues.
+
 # Build the orchestrator app using TurboRepo
 RUN pnpm turbo build --filter=@mosaic/orchestrator
 

apps/orchestrator/package.json

@@ -3,19 +3,20 @@
   "version": "0.0.20",
   "private": true,
   "scripts": {
-    "dev": "nest start --watch",
     "build": "nest build",
+    "dev": "nest start --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "prisma:generate": "prisma generate --schema=./prisma/schema.prisma",
     "start": "node dist/main.js",
-    "start:dev": "nest start --watch",
     "start:debug": "nest start --debug --watch",
+    "start:dev": "nest start --watch",
     "start:prod": "node dist/main.js",
     "test": "vitest",
-    "test:watch": "vitest watch",
     "test:e2e": "vitest run --config tests/integration/vitest.config.ts",
     "test:perf": "vitest run --config tests/performance/vitest.config.ts",
-    "typecheck": "tsc --noEmit",
+    "test:watch": "vitest watch",
-    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
-    "lint:fix": "eslint src/ --fix"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.72.1",
@@ -27,6 +28,7 @@
     "@nestjs/core": "^11.1.12",
     "@nestjs/platform-express": "^11.1.12",
     "@nestjs/throttler": "^6.5.0",
+    "@prisma/client": "^6.19.2",
     "bullmq": "^5.67.2",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
@@ -45,6 +47,7 @@
     "@types/express": "^5.0.1",
     "@types/node": "^22.13.4",
     "@vitest/coverage-v8": "^4.0.18",
+    "prisma": "^6.19.2",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.8.2",

apps/orchestrator/prisma/schema.prisma

@@ -0,0 +1 @@
+../../api/prisma/schema.prisma

apps/orchestrator/src/agent-ingestion/agent-ingestion.module.ts

@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common";
+import { PrismaModule } from "../prisma/prisma.module";
+import { AgentIngestionService } from "./agent-ingestion.service";
+
+@Module({
+  imports: [PrismaModule],
+  providers: [AgentIngestionService],
+  exports: [AgentIngestionService],
+})
+export class AgentIngestionModule {}

apps/orchestrator/src/agent-ingestion/agent-ingestion.service.ts

@@ -0,0 +1,141 @@
+import { Injectable, Logger } from "@nestjs/common";
+import type { Prisma } from "@prisma/client";
+import { PrismaService } from "../prisma/prisma.service";
+
+export type AgentConversationRole = "agent" | "user" | "system" | "operator";
+
+@Injectable()
+export class AgentIngestionService {
+  private readonly logger = new Logger(AgentIngestionService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  private toJsonValue(value: Record<string, unknown>): Prisma.InputJsonValue {
+    return value as Prisma.InputJsonValue;
+  }
+
+  async recordAgentSpawned(
+    agentId: string,
+    parentAgentId?: string,
+    missionId?: string,
+    taskId?: string,
+    agentType?: string
+  ): Promise<void> {
+    await this.prisma.agentSessionTree.upsert({
+      where: { sessionId: agentId },
+      create: {
+        sessionId: agentId,
+        parentSessionId: parentAgentId ?? null,
+        missionId,
+        taskId,
+        agentType,
+        status: "spawning",
+      },
+      update: {
+        parentSessionId: parentAgentId ?? null,
+        missionId,
+        taskId,
+        agentType,
+        status: "spawning",
+        completedAt: null,
+      },
+    });
+
+    this.logger.debug(`Recorded spawned state for agent ${agentId}`);
+  }
+
+  async recordAgentStarted(agentId: string): Promise<void> {
+    await this.prisma.agentSessionTree.upsert({
+      where: { sessionId: agentId },
+      create: {
+        sessionId: agentId,
+        status: "running",
+      },
+      update: {
+        status: "running",
+      },
+    });
+
+    this.logger.debug(`Recorded running state for agent ${agentId}`);
+  }
+
+  async recordAgentCompleted(agentId: string): Promise<void> {
+    const completedAt = new Date();
+
+    await this.prisma.agentSessionTree.upsert({
+      where: { sessionId: agentId },
+      create: {
+        sessionId: agentId,
+        status: "completed",
+        completedAt,
+      },
+      update: {
+        status: "completed",
+        completedAt,
+      },
+    });
+
+    this.logger.debug(`Recorded completed state for agent ${agentId}`);
+  }
+
+  async recordAgentFailed(agentId: string, error?: string): Promise<void> {
+    const completedAt = new Date();
+    const metadata = error ? this.toJsonValue({ error }) : undefined;
+
+    await this.prisma.agentSessionTree.upsert({
+      where: { sessionId: agentId },
+      create: {
+        sessionId: agentId,
+        status: "failed",
+        completedAt,
+        ...(metadata && { metadata }),
+      },
+      update: {
+        status: "failed",
+        completedAt,
+        ...(metadata && { metadata }),
+      },
+    });
+
+    this.logger.debug(`Recorded failed state for agent ${agentId}`);
+  }
+
+  async recordAgentKilled(agentId: string): Promise<void> {
+    const completedAt = new Date();
+
+    await this.prisma.agentSessionTree.upsert({
+      where: { sessionId: agentId },
+      create: {
+        sessionId: agentId,
+        status: "killed",
+        completedAt,
+      },
+      update: {
+        status: "killed",
+        completedAt,
+      },
+    });
+
+    this.logger.debug(`Recorded killed state for agent ${agentId}`);
+  }
+
+  async recordMessage(
+    sessionId: string,
+    role: AgentConversationRole,
+    content: string,
+    provider = "internal",
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    await this.prisma.agentConversationMessage.create({
+      data: {
+        sessionId,
+        role,
+        content,
+        provider,
+        ...(metadata && { metadata: this.toJsonValue(metadata) }),
+      },
+    });
+
+    this.logger.debug(`Recorded message for session ${sessionId}`);
+  }
+}

apps/orchestrator/src/api/agent-providers/agent-providers.controller.ts

@@ -0,0 +1,54 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from "@nestjs/common";
+import type { AgentProviderConfig } from "@prisma/client";
+import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+import { OrchestratorThrottlerGuard } from "../../common/guards/throttler.guard";
+import { AgentProvidersService } from "./agent-providers.service";
+import { CreateAgentProviderDto } from "./dto/create-agent-provider.dto";
+import { UpdateAgentProviderDto } from "./dto/update-agent-provider.dto";
+
+@Controller("agent-providers")
+@UseGuards(OrchestratorApiKeyGuard, OrchestratorThrottlerGuard)
+export class AgentProvidersController {
+  constructor(private readonly agentProvidersService: AgentProvidersService) {}
+
+  @Get()
+  async list(): Promise<AgentProviderConfig[]> {
+    return this.agentProvidersService.list();
+  }
+
+  @Get(":id")
+  async getById(@Param("id") id: string): Promise<AgentProviderConfig> {
+    return this.agentProvidersService.getById(id);
+  }
+
+  @Post()
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async create(@Body() dto: CreateAgentProviderDto): Promise<AgentProviderConfig> {
+    return this.agentProvidersService.create(dto);
+  }
+
+  @Patch(":id")
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async update(
+    @Param("id") id: string,
+    @Body() dto: UpdateAgentProviderDto
+  ): Promise<AgentProviderConfig> {
+    return this.agentProvidersService.update(id, dto);
+  }
+
+  @Delete(":id")
+  async delete(@Param("id") id: string): Promise<AgentProviderConfig> {
+    return this.agentProvidersService.delete(id);
+  }
+}

apps/orchestrator/src/api/agent-providers/agent-providers.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { PrismaModule } from "../../prisma/prisma.module";
+import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+import { AgentProvidersController } from "./agent-providers.controller";
+import { AgentProvidersService } from "./agent-providers.service";
+
+@Module({
+  imports: [PrismaModule],
+  controllers: [AgentProvidersController],
+  providers: [OrchestratorApiKeyGuard, AgentProvidersService],
+})
+export class AgentProvidersModule {}

apps/orchestrator/src/api/agent-providers/agent-providers.service.spec.ts

@@ -0,0 +1,211 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { NotFoundException } from "@nestjs/common";
+import { AgentProvidersService } from "./agent-providers.service";
+import { PrismaService } from "../../prisma/prisma.service";
+
+describe("AgentProvidersService", () => {
+  let service: AgentProvidersService;
+  let prisma: {
+    agentProviderConfig: {
+      findMany: ReturnType<typeof vi.fn>;
+      findUnique: ReturnType<typeof vi.fn>;
+      create: ReturnType<typeof vi.fn>;
+      update: ReturnType<typeof vi.fn>;
+      delete: ReturnType<typeof vi.fn>;
+    };
+  };
+
+  beforeEach(() => {
+    prisma = {
+      agentProviderConfig: {
+        findMany: vi.fn(),
+        findUnique: vi.fn(),
+        create: vi.fn(),
+        update: vi.fn(),
+        delete: vi.fn(),
+      },
+    };
+
+    service = new AgentProvidersService(prisma as unknown as PrismaService);
+  });
+
+  it("lists all provider configs", async () => {
+    const expected = [
+      {
+        id: "cfg-1",
+        workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+        name: "Primary",
+        provider: "openai",
+        gatewayUrl: "https://gateway.example.com",
+        credentials: {},
+        isActive: true,
+        createdAt: new Date("2026-03-07T18:00:00.000Z"),
+        updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+      },
+    ];
+    prisma.agentProviderConfig.findMany.mockResolvedValue(expected);
+
+    const result = await service.list();
+
+    expect(prisma.agentProviderConfig.findMany).toHaveBeenCalledWith({
+      orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    });
+    expect(result).toEqual(expected);
+  });
+
+  it("returns a single provider config", async () => {
+    const expected = {
+      id: "cfg-1",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "Primary",
+      provider: "openai",
+      gatewayUrl: "https://gateway.example.com",
+      credentials: { apiKeyRef: "vault:openai" },
+      isActive: true,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+    };
+    prisma.agentProviderConfig.findUnique.mockResolvedValue(expected);
+
+    const result = await service.getById("cfg-1");
+
+    expect(prisma.agentProviderConfig.findUnique).toHaveBeenCalledWith({
+      where: { id: "cfg-1" },
+    });
+    expect(result).toEqual(expected);
+  });
+
+  it("throws NotFoundException when provider config is missing", async () => {
+    prisma.agentProviderConfig.findUnique.mockResolvedValue(null);
+
+    await expect(service.getById("missing")).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it("creates a provider config with default credentials", async () => {
+    const created = {
+      id: "cfg-created",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "New Provider",
+      provider: "claude",
+      gatewayUrl: "https://gateway.example.com",
+      credentials: {},
+      isActive: true,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+    };
+    prisma.agentProviderConfig.create.mockResolvedValue(created);
+
+    const result = await service.create({
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "New Provider",
+      provider: "claude",
+      gatewayUrl: "https://gateway.example.com",
+    });
+
+    expect(prisma.agentProviderConfig.create).toHaveBeenCalledWith({
+      data: {
+        workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+        name: "New Provider",
+        provider: "claude",
+        gatewayUrl: "https://gateway.example.com",
+        credentials: {},
+      },
+    });
+    expect(result).toEqual(created);
+  });
+
+  it("updates a provider config", async () => {
+    prisma.agentProviderConfig.findUnique.mockResolvedValue({
+      id: "cfg-1",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "Primary",
+      provider: "openai",
+      gatewayUrl: "https://gateway.example.com",
+      credentials: {},
+      isActive: true,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+    });
+
+    const updated = {
+      id: "cfg-1",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "Secondary",
+      provider: "openai",
+      gatewayUrl: "https://gateway2.example.com",
+      credentials: { apiKeyRef: "vault:new" },
+      isActive: false,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T19:00:00.000Z"),
+    };
+    prisma.agentProviderConfig.update.mockResolvedValue(updated);
+
+    const result = await service.update("cfg-1", {
+      name: "Secondary",
+      gatewayUrl: "https://gateway2.example.com",
+      credentials: { apiKeyRef: "vault:new" },
+      isActive: false,
+    });
+
+    expect(prisma.agentProviderConfig.update).toHaveBeenCalledWith({
+      where: { id: "cfg-1" },
+      data: {
+        name: "Secondary",
+        gatewayUrl: "https://gateway2.example.com",
+        credentials: { apiKeyRef: "vault:new" },
+        isActive: false,
+      },
+    });
+    expect(result).toEqual(updated);
+  });
+
+  it("throws NotFoundException when updating a missing provider config", async () => {
+    prisma.agentProviderConfig.findUnique.mockResolvedValue(null);
+
+    await expect(service.update("missing", { name: "Updated" })).rejects.toBeInstanceOf(
+      NotFoundException
+    );
+    expect(prisma.agentProviderConfig.update).not.toHaveBeenCalled();
+  });
+
+  it("deletes a provider config", async () => {
+    prisma.agentProviderConfig.findUnique.mockResolvedValue({
+      id: "cfg-1",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "Primary",
+      provider: "openai",
+      gatewayUrl: "https://gateway.example.com",
+      credentials: {},
+      isActive: true,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+    });
+
+    const deleted = {
+      id: "cfg-1",
+      workspaceId: "8bcd7eda-a122-4d6c-adfd-b152f6f75369",
+      name: "Primary",
+      provider: "openai",
+      gatewayUrl: "https://gateway.example.com",
+      credentials: {},
+      isActive: true,
+      createdAt: new Date("2026-03-07T18:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T18:00:00.000Z"),
+    };
+    prisma.agentProviderConfig.delete.mockResolvedValue(deleted);
+
+    const result = await service.delete("cfg-1");
+
+    expect(prisma.agentProviderConfig.delete).toHaveBeenCalledWith({
+      where: { id: "cfg-1" },
+    });
+    expect(result).toEqual(deleted);
+  });
+
+  it("throws NotFoundException when deleting a missing provider config", async () => {
+    prisma.agentProviderConfig.findUnique.mockResolvedValue(null);
+
+    await expect(service.delete("missing")).rejects.toBeInstanceOf(NotFoundException);
+    expect(prisma.agentProviderConfig.delete).not.toHaveBeenCalled();
+  });
+});

apps/orchestrator/src/api/agent-providers/agent-providers.service.ts

@@ -0,0 +1,71 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import type { AgentProviderConfig, Prisma } from "@prisma/client";
+import { PrismaService } from "../../prisma/prisma.service";
+import { CreateAgentProviderDto } from "./dto/create-agent-provider.dto";
+import { UpdateAgentProviderDto } from "./dto/update-agent-provider.dto";
+
+@Injectable()
+export class AgentProvidersService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async list(): Promise<AgentProviderConfig[]> {
+    return this.prisma.agentProviderConfig.findMany({
+      orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    });
+  }
+
+  async getById(id: string): Promise<AgentProviderConfig> {
+    const providerConfig = await this.prisma.agentProviderConfig.findUnique({
+      where: { id },
+    });
+
+    if (!providerConfig) {
+      throw new NotFoundException(`Agent provider config with id ${id} not found`);
+    }
+
+    return providerConfig;
+  }
+
+  async create(dto: CreateAgentProviderDto): Promise<AgentProviderConfig> {
+    return this.prisma.agentProviderConfig.create({
+      data: {
+        workspaceId: dto.workspaceId,
+        name: dto.name,
+        provider: dto.provider,
+        gatewayUrl: dto.gatewayUrl,
+        credentials: this.toJsonValue(dto.credentials ?? {}),
+        ...(dto.isActive !== undefined ? { isActive: dto.isActive } : {}),
+      },
+    });
+  }
+
+  async update(id: string, dto: UpdateAgentProviderDto): Promise<AgentProviderConfig> {
+    await this.getById(id);
+
+    const data: Prisma.AgentProviderConfigUpdateInput = {
+      ...(dto.workspaceId !== undefined ? { workspaceId: dto.workspaceId } : {}),
+      ...(dto.name !== undefined ? { name: dto.name } : {}),
+      ...(dto.provider !== undefined ? { provider: dto.provider } : {}),
+      ...(dto.gatewayUrl !== undefined ? { gatewayUrl: dto.gatewayUrl } : {}),
+      ...(dto.isActive !== undefined ? { isActive: dto.isActive } : {}),
+      ...(dto.credentials !== undefined ? { credentials: this.toJsonValue(dto.credentials) } : {}),
+    };
+
+    return this.prisma.agentProviderConfig.update({
+      where: { id },
+      data,
+    });
+  }
+
+  async delete(id: string): Promise<AgentProviderConfig> {
+    await this.getById(id);
+
+    return this.prisma.agentProviderConfig.delete({
+      where: { id },
+    });
+  }
+
+  private toJsonValue(value: Record<string, unknown>): Prisma.InputJsonValue {
+    return value as Prisma.InputJsonValue;
+  }
+}

apps/orchestrator/src/api/agent-providers/dto/create-agent-provider.dto.ts

@@ -0,0 +1,26 @@
+import { IsBoolean, IsNotEmpty, IsObject, IsOptional, IsString, IsUUID } from "class-validator";
+
+export class CreateAgentProviderDto {
+  @IsUUID()
+  workspaceId!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  name!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  provider!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  gatewayUrl!: string;
+
+  @IsOptional()
+  @IsObject()
+  credentials?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsBoolean()
+  isActive?: boolean;
+}

apps/orchestrator/src/api/agent-providers/dto/update-agent-provider.dto.ts

@@ -0,0 +1,30 @@
+import { IsBoolean, IsNotEmpty, IsObject, IsOptional, IsString, IsUUID } from "class-validator";
+
+export class UpdateAgentProviderDto {
+  @IsOptional()
+  @IsUUID()
+  workspaceId?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  name?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  provider?: string;
+
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  gatewayUrl?: string;
+
+  @IsOptional()
+  @IsObject()
+  credentials?: Record<string, unknown>;
+
+  @IsOptional()
+  @IsBoolean()
+  isActive?: boolean;
+}

apps/orchestrator/src/api/agents/agent-control.service.spec.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentControlService } from "./agent-control.service";
+import { PrismaService } from "../../prisma/prisma.service";
+import { KillswitchService } from "../../killswitch/killswitch.service";
+
+describe("AgentControlService", () => {
+  let service: AgentControlService;
+  let prisma: {
+    agentSessionTree: {
+      findUnique: ReturnType<typeof vi.fn>;
+      updateMany: ReturnType<typeof vi.fn>;
+    };
+    agentConversationMessage: {
+      create: ReturnType<typeof vi.fn>;
+    };
+    operatorAuditLog: {
+      create: ReturnType<typeof vi.fn>;
+    };
+  };
+  let killswitchService: {
+    killAgent: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    prisma = {
+      agentSessionTree: {
+        findUnique: vi.fn(),
+        updateMany: vi.fn().mockResolvedValue({ count: 1 }),
+      },
+      agentConversationMessage: {
+        create: vi.fn().mockResolvedValue(undefined),
+      },
+      operatorAuditLog: {
+        create: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+
+    killswitchService = {
+      killAgent: vi.fn().mockResolvedValue(undefined),
+    };
+
+    service = new AgentControlService(
+      prisma as unknown as PrismaService,
+      killswitchService as unknown as KillswitchService
+    );
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("injectMessage", () => {
+    it("creates conversation message and audit log when tree entry exists", async () => {
+      prisma.agentSessionTree.findUnique.mockResolvedValue({ id: "tree-1" });
+
+      await service.injectMessage("agent-123", "operator-abc", "Please continue");
+
+      expect(prisma.agentSessionTree.findUnique).toHaveBeenCalledWith({
+        where: { sessionId: "agent-123" },
+        select: { id: true },
+      });
+      expect(prisma.agentConversationMessage.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-123",
+          role: "operator",
+          content: "Please continue",
+          provider: "internal",
+          metadata: {},
+        },
+      });
+      expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-123",
+          userId: "operator-abc",
+          provider: "internal",
+          action: "inject",
+          metadata: {
+            payload: {
+              message: "Please continue",
+            },
+          },
+        },
+      });
+    });
+
+    it("creates only audit log when no tree entry exists", async () => {
+      prisma.agentSessionTree.findUnique.mockResolvedValue(null);
+
+      await service.injectMessage("agent-456", "operator-def", "Nudge message");
+
+      expect(prisma.agentConversationMessage.create).not.toHaveBeenCalled();
+      expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-456",
+          userId: "operator-def",
+          provider: "internal",
+          action: "inject",
+          metadata: {
+            payload: {
+              message: "Nudge message",
+            },
+          },
+        },
+      });
+    });
+  });
+
+  describe("pauseAgent", () => {
+    it("updates tree status to paused and creates audit log", async () => {
+      await service.pauseAgent("agent-789", "operator-pause");
+
+      expect(prisma.agentSessionTree.updateMany).toHaveBeenCalledWith({
+        where: { sessionId: "agent-789" },
+        data: { status: "paused" },
+      });
+      expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-789",
+          userId: "operator-pause",
+          provider: "internal",
+          action: "pause",
+          metadata: {
+            payload: {},
+          },
+        },
+      });
+    });
+  });
+
+  describe("resumeAgent", () => {
+    it("updates tree status to running and creates audit log", async () => {
+      await service.resumeAgent("agent-321", "operator-resume");
+
+      expect(prisma.agentSessionTree.updateMany).toHaveBeenCalledWith({
+        where: { sessionId: "agent-321" },
+        data: { status: "running" },
+      });
+      expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-321",
+          userId: "operator-resume",
+          provider: "internal",
+          action: "resume",
+          metadata: {
+            payload: {},
+          },
+        },
+      });
+    });
+  });
+
+  describe("killAgent", () => {
+    it("delegates kill to killswitch and logs audit", async () => {
+      await service.killAgent("agent-654", "operator-kill", false);
+
+      expect(killswitchService.killAgent).toHaveBeenCalledWith("agent-654");
+      expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+        data: {
+          sessionId: "agent-654",
+          userId: "operator-kill",
+          provider: "internal",
+          action: "kill",
+          metadata: {
+            payload: {
+              force: false,
+            },
+          },
+        },
+      });
+    });
+  });
+});

apps/orchestrator/src/api/agents/agent-control.service.ts

@@ -0,0 +1,77 @@
+import { Injectable } from "@nestjs/common";
+import type { Prisma } from "@prisma/client";
+import { KillswitchService } from "../../killswitch/killswitch.service";
+import { PrismaService } from "../../prisma/prisma.service";
+
+@Injectable()
+export class AgentControlService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly killswitchService: KillswitchService
+  ) {}
+
+  private toJsonValue(value: Record<string, unknown>): Prisma.InputJsonValue {
+    return value as Prisma.InputJsonValue;
+  }
+
+  private async createOperatorAuditLog(
+    agentId: string,
+    operatorId: string,
+    action: "inject" | "pause" | "resume" | "kill",
+    payload: Record<string, unknown>
+  ): Promise<void> {
+    await this.prisma.operatorAuditLog.create({
+      data: {
+        sessionId: agentId,
+        userId: operatorId,
+        provider: "internal",
+        action,
+        metadata: this.toJsonValue({ payload }),
+      },
+    });
+  }
+
+  async injectMessage(agentId: string, operatorId: string, message: string): Promise<void> {
+    const treeEntry = await this.prisma.agentSessionTree.findUnique({
+      where: { sessionId: agentId },
+      select: { id: true },
+    });
+
+    if (treeEntry) {
+      await this.prisma.agentConversationMessage.create({
+        data: {
+          sessionId: agentId,
+          role: "operator",
+          content: message,
+          provider: "internal",
+          metadata: this.toJsonValue({}),
+        },
+      });
+    }
+
+    await this.createOperatorAuditLog(agentId, operatorId, "inject", { message });
+  }
+
+  async pauseAgent(agentId: string, operatorId: string): Promise<void> {
+    await this.prisma.agentSessionTree.updateMany({
+      where: { sessionId: agentId },
+      data: { status: "paused" },
+    });
+
+    await this.createOperatorAuditLog(agentId, operatorId, "pause", {});
+  }
+
+  async resumeAgent(agentId: string, operatorId: string): Promise<void> {
+    await this.prisma.agentSessionTree.updateMany({
+      where: { sessionId: agentId },
+      data: { status: "running" },
+    });
+
+    await this.createOperatorAuditLog(agentId, operatorId, "resume", {});
+  }
+
+  async killAgent(agentId: string, operatorId: string, force = true): Promise<void> {
+    await this.killswitchService.killAgent(agentId);
+    await this.createOperatorAuditLog(agentId, operatorId, "kill", { force });
+  }
+}

apps/orchestrator/src/api/agents/agent-messages.service.spec.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentMessagesService } from "./agent-messages.service";
+import { PrismaService } from "../../prisma/prisma.service";
+
+describe("AgentMessagesService", () => {
+  let service: AgentMessagesService;
+  let prisma: {
+    agentConversationMessage: {
+      findMany: ReturnType<typeof vi.fn>;
+      count: ReturnType<typeof vi.fn>;
+    };
+  };
+
+  beforeEach(() => {
+    prisma = {
+      agentConversationMessage: {
+        findMany: vi.fn(),
+        count: vi.fn(),
+      },
+    };
+
+    service = new AgentMessagesService(prisma as unknown as PrismaService);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("getMessages", () => {
+    it("returns paginated messages from Prisma", async () => {
+      const sessionId = "agent-123";
+      const messages = [
+        {
+          id: "msg-1",
+          sessionId,
+          provider: "internal",
+          role: "assistant",
+          content: "First message",
+          timestamp: new Date("2026-03-07T16:00:00.000Z"),
+          metadata: {},
+        },
+        {
+          id: "msg-2",
+          sessionId,
+          provider: "internal",
+          role: "user",
+          content: "Second message",
+          timestamp: new Date("2026-03-07T15:59:00.000Z"),
+          metadata: {},
+        },
+      ];
+
+      prisma.agentConversationMessage.findMany.mockResolvedValue(messages);
+      prisma.agentConversationMessage.count.mockResolvedValue(2);
+
+      const result = await service.getMessages(sessionId, 50, 0);
+
+      expect(prisma.agentConversationMessage.findMany).toHaveBeenCalledWith({
+        where: { sessionId },
+        orderBy: { timestamp: "desc" },
+        take: 50,
+        skip: 0,
+      });
+      expect(prisma.agentConversationMessage.count).toHaveBeenCalledWith({ where: { sessionId } });
+      expect(result).toEqual({
+        messages,
+        total: 2,
+      });
+    });
+
+    it("applies limit and cursor (skip) correctly", async () => {
+      const sessionId = "agent-456";
+      const limit = 10;
+      const cursor = 20;
+
+      prisma.agentConversationMessage.findMany.mockResolvedValue([]);
+      prisma.agentConversationMessage.count.mockResolvedValue(42);
+
+      await service.getMessages(sessionId, limit, cursor);
+
+      expect(prisma.agentConversationMessage.findMany).toHaveBeenCalledWith({
+        where: { sessionId },
+        orderBy: { timestamp: "desc" },
+        take: limit,
+        skip: cursor,
+      });
+    });
+
+    it("returns empty messages array when no messages exist", async () => {
+      const sessionId = "agent-empty";
+
+      prisma.agentConversationMessage.findMany.mockResolvedValue([]);
+      prisma.agentConversationMessage.count.mockResolvedValue(0);
+
+      const result = await service.getMessages(sessionId, 25, 0);
+
+      expect(result).toEqual({
+        messages: [],
+        total: 0,
+      });
+    });
+  });
+});

apps/orchestrator/src/api/agents/agent-messages.service.ts

@@ -0,0 +1,84 @@
+import { Injectable } from "@nestjs/common";
+import { type AgentConversationMessage, type Prisma } from "@prisma/client";
+import { PrismaService } from "../../prisma/prisma.service";
+
+@Injectable()
+export class AgentMessagesService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getMessages(
+    sessionId: string,
+    limit: number,
+    skip: number
+  ): Promise<{
+    messages: AgentConversationMessage[];
+    total: number;
+  }> {
+    const where = { sessionId };
+
+    const [messages, total] = await Promise.all([
+      this.prisma.agentConversationMessage.findMany({
+        where,
+        orderBy: {
+          timestamp: "desc",
+        },
+        take: limit,
+        skip,
+      }),
+      this.prisma.agentConversationMessage.count({ where }),
+    ]);
+
+    return {
+      messages,
+      total,
+    };
+  }
+
+  async getReplayMessages(sessionId: string, limit = 50): Promise<AgentConversationMessage[]> {
+    const messages = await this.prisma.agentConversationMessage.findMany({
+      where: { sessionId },
+      orderBy: {
+        timestamp: "desc",
+      },
+      take: limit,
+    });
+
+    return messages.reverse();
+  }
+
+  async getMessagesAfter(
+    sessionId: string,
+    lastSeenTimestamp: Date,
+    lastSeenMessageId: string | null
+  ): Promise<AgentConversationMessage[]> {
+    const where: Prisma.AgentConversationMessageWhereInput = {
+      sessionId,
+      ...(lastSeenMessageId
+        ? {
+            OR: [
+              {
+                timestamp: {
+                  gt: lastSeenTimestamp,
+                },
+              },
+              {
+                timestamp: lastSeenTimestamp,
+                id: {
+                  gt: lastSeenMessageId,
+                },
+              },
+            ],
+          }
+        : {
+            timestamp: {
+              gt: lastSeenTimestamp,
+            },
+          }),
+    };
+
+    return this.prisma.agentConversationMessage.findMany({
+      where,
+      orderBy: [{ timestamp: "asc" }, { id: "asc" }],
+    });
+  }
+}

apps/orchestrator/src/api/agents/agent-provider.registry.spec.ts

@@ -0,0 +1,202 @@
+import { Logger } from "@nestjs/common";
+import type {
+  AgentMessage,
+  AgentSession,
+  AgentSessionList,
+  IAgentProvider,
+  InjectResult,
+} from "@mosaic/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AgentProviderRegistry } from "./agent-provider.registry";
+import { InternalAgentProvider } from "./internal-agent.provider";
+
+type MockProvider = IAgentProvider & {
+  listSessions: ReturnType<typeof vi.fn>;
+  getSession: ReturnType<typeof vi.fn>;
+};
+
+const emptyMessageStream = async function* (): AsyncIterable<AgentMessage> {
+  return;
+};
+
+const createProvider = (providerId: string, sessions: AgentSession[] = []): MockProvider => {
+  return {
+    providerId,
+    providerType: providerId,
+    displayName: providerId,
+    listSessions: vi.fn().mockResolvedValue({
+      sessions,
+      total: sessions.length,
+    } as AgentSessionList),
+    getSession: vi.fn().mockResolvedValue(null),
+    getMessages: vi.fn().mockResolvedValue([]),
+    injectMessage: vi.fn().mockResolvedValue({ accepted: true } as InjectResult),
+    pauseSession: vi.fn().mockResolvedValue(undefined),
+    resumeSession: vi.fn().mockResolvedValue(undefined),
+    killSession: vi.fn().mockResolvedValue(undefined),
+    streamMessages: vi.fn().mockReturnValue(emptyMessageStream()),
+    isAvailable: vi.fn().mockResolvedValue(true),
+  };
+};
+
+describe("AgentProviderRegistry", () => {
+  let registry: AgentProviderRegistry;
+  let internalProvider: MockProvider;
+
+  beforeEach(() => {
+    internalProvider = createProvider("internal");
+    registry = new AgentProviderRegistry(internalProvider as unknown as InternalAgentProvider);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("registers InternalAgentProvider on module init", () => {
+    registry.onModuleInit();
+
+    expect(registry.getProvider("internal")).toBe(internalProvider);
+  });
+
+  it("registers providers and returns null for unknown provider ids", () => {
+    const externalProvider = createProvider("openclaw");
+
+    registry.registerProvider(externalProvider);
+
+    expect(registry.getProvider("openclaw")).toBe(externalProvider);
+    expect(registry.getProvider("missing")).toBeNull();
+  });
+
+  it("aggregates and sorts sessions from all providers", async () => {
+    const internalSessions: AgentSession[] = [
+      {
+        id: "session-older",
+        providerId: "internal",
+        providerType: "internal",
+        status: "active",
+        createdAt: new Date("2026-03-07T10:00:00.000Z"),
+        updatedAt: new Date("2026-03-07T10:10:00.000Z"),
+      },
+    ];
+
+    const externalSessions: AgentSession[] = [
+      {
+        id: "session-newer",
+        providerId: "openclaw",
+        providerType: "external",
+        status: "paused",
+        createdAt: new Date("2026-03-07T09:00:00.000Z"),
+        updatedAt: new Date("2026-03-07T10:20:00.000Z"),
+      },
+    ];
+
+    internalProvider.listSessions.mockResolvedValue({
+      sessions: internalSessions,
+      total: internalSessions.length,
+    } as AgentSessionList);
+
+    const externalProvider = createProvider("openclaw", externalSessions);
+    registry.onModuleInit();
+    registry.registerProvider(externalProvider);
+
+    const result = await registry.listAllSessions();
+
+    expect(result.map((session) => session.id)).toEqual(["session-newer", "session-older"]);
+    expect(internalProvider.listSessions).toHaveBeenCalledTimes(1);
+    expect(externalProvider.listSessions).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips provider failures and logs warning", async () => {
+    const warnSpy = vi.spyOn(Logger.prototype, "warn").mockImplementation(() => undefined);
+
+    const healthyProvider = createProvider("healthy", [
+      {
+        id: "session-1",
+        providerId: "healthy",
+        providerType: "external",
+        status: "active",
+        createdAt: new Date("2026-03-07T11:00:00.000Z"),
+        updatedAt: new Date("2026-03-07T11:00:00.000Z"),
+      },
+    ]);
+
+    const failingProvider = createProvider("failing");
+    failingProvider.listSessions.mockRejectedValue(new Error("provider offline"));
+
+    registry.onModuleInit();
+    registry.registerProvider(healthyProvider);
+    registry.registerProvider(failingProvider);
+
+    const result = await registry.listAllSessions();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.id).toBe("session-1");
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to list sessions for provider failing")
+    );
+  });
+
+  it("finds a provider for an existing session", async () => {
+    const targetSession: AgentSession = {
+      id: "session-found",
+      providerId: "openclaw",
+      providerType: "external",
+      status: "active",
+      createdAt: new Date("2026-03-07T12:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T12:10:00.000Z"),
+    };
+
+    const openclawProvider = createProvider("openclaw");
+    openclawProvider.getSession.mockResolvedValue(targetSession);
+
+    registry.onModuleInit();
+    registry.registerProvider(openclawProvider);
+
+    const result = await registry.getProviderForSession(targetSession.id);
+
+    expect(result).toEqual({
+      provider: openclawProvider,
+      session: targetSession,
+    });
+    expect(internalProvider.getSession).toHaveBeenCalledWith(targetSession.id);
+    expect(openclawProvider.getSession).toHaveBeenCalledWith(targetSession.id);
+  });
+
+  it("returns null when no provider has the requested session", async () => {
+    const openclawProvider = createProvider("openclaw");
+
+    registry.onModuleInit();
+    registry.registerProvider(openclawProvider);
+
+    await expect(registry.getProviderForSession("missing-session")).resolves.toBeNull();
+  });
+
+  it("continues searching providers when getSession throws", async () => {
+    const warnSpy = vi.spyOn(Logger.prototype, "warn").mockImplementation(() => undefined);
+    const failingProvider = createProvider("failing");
+    failingProvider.getSession.mockRejectedValue(new Error("provider timeout"));
+
+    const healthySession: AgentSession = {
+      id: "session-healthy",
+      providerId: "healthy",
+      providerType: "external",
+      status: "active",
+      createdAt: new Date("2026-03-07T12:15:00.000Z"),
+      updatedAt: new Date("2026-03-07T12:16:00.000Z"),
+    };
+
+    const healthyProvider = createProvider("healthy");
+    healthyProvider.getSession.mockResolvedValue(healthySession);
+
+    registry.onModuleInit();
+    registry.registerProvider(failingProvider);
+    registry.registerProvider(healthyProvider);
+
+    const result = await registry.getProviderForSession(healthySession.id);
+
+    expect(result).toEqual({ provider: healthyProvider, session: healthySession });
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Failed to get session session-healthy for provider failing")
+    );
+  });
+});

apps/orchestrator/src/api/agents/agent-provider.registry.ts

@@ -0,0 +1,79 @@
+import { Injectable, Logger, OnModuleInit } from "@nestjs/common";
+import type { AgentSession, IAgentProvider } from "@mosaic/shared";
+import { InternalAgentProvider } from "./internal-agent.provider";
+
+@Injectable()
+export class AgentProviderRegistry implements OnModuleInit {
+  private readonly logger = new Logger(AgentProviderRegistry.name);
+  private readonly providers = new Map<string, IAgentProvider>();
+
+  constructor(private readonly internalProvider: InternalAgentProvider) {}
+
+  onModuleInit(): void {
+    this.registerProvider(this.internalProvider);
+  }
+
+  registerProvider(provider: IAgentProvider): void {
+    const existingProvider = this.providers.get(provider.providerId);
+    if (existingProvider !== undefined) {
+      this.logger.warn(`Replacing existing provider registration for ${provider.providerId}`);
+    }
+
+    this.providers.set(provider.providerId, provider);
+  }
+
+  getProvider(providerId: string): IAgentProvider | null {
+    return this.providers.get(providerId) ?? null;
+  }
+
+  async getProviderForSession(
+    sessionId: string
+  ): Promise<{ provider: IAgentProvider; session: AgentSession } | null> {
+    for (const provider of this.providers.values()) {
+      try {
+        const session = await provider.getSession(sessionId);
+        if (session !== null) {
+          return {
+            provider,
+            session,
+          };
+        }
+      } catch (error) {
+        this.logger.warn(
+          `Failed to get session ${sessionId} for provider ${provider.providerId}: ${this.toErrorMessage(error)}`
+        );
+      }
+    }
+
+    return null;
+  }
+
+  async listAllSessions(): Promise<AgentSession[]> {
+    const providers = [...this.providers.values()];
+    const sessionsByProvider = await Promise.all(
+      providers.map(async (provider) => {
+        try {
+          const { sessions } = await provider.listSessions();
+          return sessions;
+        } catch (error) {
+          this.logger.warn(
+            `Failed to list sessions for provider ${provider.providerId}: ${this.toErrorMessage(error)}`
+          );
+          return [];
+        }
+      })
+    );
+
+    return sessionsByProvider
+      .flat()
+      .sort((left, right) => right.updatedAt.getTime() - left.updatedAt.getTime());
+  }
+
+  private toErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return String(error);
+  }
+}

apps/orchestrator/src/api/agents/agent-tree.service.spec.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentTreeService } from "./agent-tree.service";
+import { PrismaService } from "../../prisma/prisma.service";
+
+describe("AgentTreeService", () => {
+  let service: AgentTreeService;
+  let prisma: {
+    agentSessionTree: {
+      findMany: ReturnType<typeof vi.fn>;
+      count: ReturnType<typeof vi.fn>;
+      findUnique: ReturnType<typeof vi.fn>;
+    };
+  };
+
+  beforeEach(() => {
+    prisma = {
+      agentSessionTree: {
+        findMany: vi.fn(),
+        count: vi.fn(),
+        findUnique: vi.fn(),
+      },
+    };
+
+    service = new AgentTreeService(prisma as unknown as PrismaService);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("listSessions", () => {
+    it("returns paginated sessions and cursor", async () => {
+      const sessions = [
+        {
+          id: "tree-2",
+          sessionId: "agent-2",
+          parentSessionId: null,
+          provider: "internal",
+          missionId: null,
+          taskId: "task-2",
+          taskSource: "queue",
+          agentType: "worker",
+          status: "running",
+          spawnedAt: new Date("2026-03-07T11:00:00.000Z"),
+          completedAt: null,
+          metadata: {},
+        },
+        {
+          id: "tree-1",
+          sessionId: "agent-1",
+          parentSessionId: null,
+          provider: "internal",
+          missionId: null,
+          taskId: "task-1",
+          taskSource: "queue",
+          agentType: "worker",
+          status: "running",
+          spawnedAt: new Date("2026-03-07T10:00:00.000Z"),
+          completedAt: null,
+          metadata: {},
+        },
+      ];
+
+      prisma.agentSessionTree.findMany.mockResolvedValue(sessions);
+      prisma.agentSessionTree.count.mockResolvedValue(7);
+
+      const result = await service.listSessions(undefined, 2);
+
+      expect(prisma.agentSessionTree.findMany).toHaveBeenCalledWith({
+        where: undefined,
+        orderBy: [{ spawnedAt: "desc" }, { sessionId: "desc" }],
+        take: 2,
+      });
+      expect(prisma.agentSessionTree.count).toHaveBeenCalledWith();
+      expect(result.sessions).toEqual(sessions);
+      expect(result.total).toBe(7);
+      expect(result.cursor).toBeTypeOf("string");
+    });
+
+    it("applies cursor filter when provided", async () => {
+      prisma.agentSessionTree.findMany.mockResolvedValue([]);
+      prisma.agentSessionTree.count.mockResolvedValue(0);
+
+      const cursorDate = "2026-03-07T10:00:00.000Z";
+      const cursorSessionId = "agent-5";
+      const cursor = Buffer.from(
+        JSON.stringify({
+          spawnedAt: cursorDate,
+          sessionId: cursorSessionId,
+        }),
+        "utf8"
+      ).toString("base64url");
+
+      await service.listSessions(cursor, 25);
+
+      expect(prisma.agentSessionTree.findMany).toHaveBeenCalledWith({
+        where: {
+          OR: [
+            {
+              spawnedAt: {
+                lt: new Date(cursorDate),
+              },
+            },
+            {
+              spawnedAt: new Date(cursorDate),
+              sessionId: {
+                lt: cursorSessionId,
+              },
+            },
+          ],
+        },
+        orderBy: [{ spawnedAt: "desc" }, { sessionId: "desc" }],
+        take: 25,
+      });
+    });
+
+    it("ignores invalid cursor values", async () => {
+      prisma.agentSessionTree.findMany.mockResolvedValue([]);
+      prisma.agentSessionTree.count.mockResolvedValue(0);
+
+      await service.listSessions("invalid-cursor", 10);
+
+      expect(prisma.agentSessionTree.findMany).toHaveBeenCalledWith({
+        where: undefined,
+        orderBy: [{ spawnedAt: "desc" }, { sessionId: "desc" }],
+        take: 10,
+      });
+    });
+  });
+
+  describe("getSession", () => {
+    it("returns matching session entry", async () => {
+      const session = {
+        id: "tree-1",
+        sessionId: "agent-123",
+        parentSessionId: null,
+        provider: "internal",
+        missionId: null,
+        taskId: "task-1",
+        taskSource: "queue",
+        agentType: "worker",
+        status: "running",
+        spawnedAt: new Date("2026-03-07T11:00:00.000Z"),
+        completedAt: null,
+        metadata: {},
+      };
+      prisma.agentSessionTree.findUnique.mockResolvedValue(session);
+
+      const result = await service.getSession("agent-123");
+
+      expect(prisma.agentSessionTree.findUnique).toHaveBeenCalledWith({
+        where: { sessionId: "agent-123" },
+      });
+      expect(result).toEqual(session);
+    });
+
+    it("returns null when session does not exist", async () => {
+      prisma.agentSessionTree.findUnique.mockResolvedValue(null);
+
+      const result = await service.getSession("agent-missing");
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getTree", () => {
+    it("returns mapped entries from Prisma", async () => {
+      prisma.agentSessionTree.findMany.mockResolvedValue([
+        {
+          id: "tree-1",
+          sessionId: "agent-1",
+          parentSessionId: "agent-root",
+          provider: "internal",
+          missionId: "mission-1",
+          taskId: "task-1",
+          taskSource: "queue",
+          agentType: "worker",
+          status: "running",
+          spawnedAt: new Date("2026-03-07T10:00:00.000Z"),
+          completedAt: new Date("2026-03-07T11:00:00.000Z"),
+          metadata: {},
+        },
+      ]);
+
+      const result = await service.getTree();
+
+      expect(prisma.agentSessionTree.findMany).toHaveBeenCalledWith({
+        orderBy: { spawnedAt: "desc" },
+        take: 200,
+      });
+      expect(result).toEqual([
+        {
+          sessionId: "agent-1",
+          parentSessionId: "agent-root",
+          status: "running",
+          agentType: "worker",
+          taskSource: "queue",
+          spawnedAt: "2026-03-07T10:00:00.000Z",
+          completedAt: "2026-03-07T11:00:00.000Z",
+        },
+      ]);
+    });
+
+    it("returns empty array when no entries exist", async () => {
+      prisma.agentSessionTree.findMany.mockResolvedValue([]);
+
+      const result = await service.getTree();
+
+      expect(result).toEqual([]);
+    });
+
+    it("maps null parentSessionId and completedAt correctly", async () => {
+      prisma.agentSessionTree.findMany.mockResolvedValue([
+        {
+          id: "tree-2",
+          sessionId: "agent-root",
+          parentSessionId: null,
+          provider: "internal",
+          missionId: null,
+          taskId: null,
+          taskSource: null,
+          agentType: null,
+          status: "spawning",
+          spawnedAt: new Date("2026-03-07T09:00:00.000Z"),
+          completedAt: null,
+          metadata: {},
+        },
+      ]);
+
+      const result = await service.getTree();
+
+      expect(result).toEqual([
+        {
+          sessionId: "agent-root",
+          parentSessionId: null,
+          status: "spawning",
+          agentType: null,
+          taskSource: null,
+          spawnedAt: "2026-03-07T09:00:00.000Z",
+          completedAt: null,
+        },
+      ]);
+    });
+  });
+});

apps/orchestrator/src/api/agents/agent-tree.service.ts

@@ -0,0 +1,146 @@
+import { Injectable } from "@nestjs/common";
+import type { AgentSessionTree, Prisma } from "@prisma/client";
+import { AgentTreeResponseDto } from "./dto/agent-tree-response.dto";
+import { PrismaService } from "../../prisma/prisma.service";
+
+const DEFAULT_PAGE_LIMIT = 50;
+const MAX_PAGE_LIMIT = 200;
+
+interface SessionCursor {
+  spawnedAt: Date;
+  sessionId: string;
+}
+
+export interface AgentSessionTreeListResult {
+  sessions: AgentSessionTree[];
+  total: number;
+  cursor?: string;
+}
+
+@Injectable()
+export class AgentTreeService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async listSessions(
+    cursor?: string,
+    limit = DEFAULT_PAGE_LIMIT
+  ): Promise<AgentSessionTreeListResult> {
+    const safeLimit = this.normalizeLimit(limit);
+    const parsedCursor = this.parseCursor(cursor);
+
+    const where: Prisma.AgentSessionTreeWhereInput | undefined = parsedCursor
+      ? {
+          OR: [
+            {
+              spawnedAt: {
+                lt: parsedCursor.spawnedAt,
+              },
+            },
+            {
+              spawnedAt: parsedCursor.spawnedAt,
+              sessionId: {
+                lt: parsedCursor.sessionId,
+              },
+            },
+          ],
+        }
+      : undefined;
+
+    const [sessions, total] = await Promise.all([
+      this.prisma.agentSessionTree.findMany({
+        where,
+        orderBy: [{ spawnedAt: "desc" }, { sessionId: "desc" }],
+        take: safeLimit,
+      }),
+      this.prisma.agentSessionTree.count(),
+    ]);
+
+    const nextCursor =
+      sessions.length === safeLimit
+        ? this.serializeCursor(sessions[sessions.length - 1])
+        : undefined;
+
+    return {
+      sessions,
+      total,
+      ...(nextCursor !== undefined ? { cursor: nextCursor } : {}),
+    };
+  }
+
+  async getSession(sessionId: string): Promise<AgentSessionTree | null> {
+    return this.prisma.agentSessionTree.findUnique({
+      where: { sessionId },
+    });
+  }
+
+  async getTree(): Promise<AgentTreeResponseDto[]> {
+    const entries = await this.prisma.agentSessionTree.findMany({
+      orderBy: { spawnedAt: "desc" },
+      take: 200,
+    });
+
+    const response: AgentTreeResponseDto[] = [];
+    for (const entry of entries) {
+      response.push({
+        sessionId: entry.sessionId,
+        parentSessionId: entry.parentSessionId ?? null,
+        status: entry.status,
+        agentType: entry.agentType ?? null,
+        taskSource: entry.taskSource ?? null,
+        spawnedAt: entry.spawnedAt.toISOString(),
+        completedAt: entry.completedAt?.toISOString() ?? null,
+      });
+    }
+
+    return response;
+  }
+
+  private normalizeLimit(limit: number): number {
+    const normalized = Number.isFinite(limit) ? Math.trunc(limit) : DEFAULT_PAGE_LIMIT;
+    if (normalized < 1) {
+      return 1;
+    }
+
+    return Math.min(normalized, MAX_PAGE_LIMIT);
+  }
+
+  private serializeCursor(entry: Pick<AgentSessionTree, "spawnedAt" | "sessionId">): string {
+    return Buffer.from(
+      JSON.stringify({
+        spawnedAt: entry.spawnedAt.toISOString(),
+        sessionId: entry.sessionId,
+      }),
+      "utf8"
+    ).toString("base64url");
+  }
+
+  private parseCursor(cursor?: string): SessionCursor | null {
+    if (!cursor) {
+      return null;
+    }
+
+    try {
+      const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+      const parsed = JSON.parse(decoded) as {
+        spawnedAt?: string;
+        sessionId?: string;
+      };
+
+      if (typeof parsed.spawnedAt !== "string" || typeof parsed.sessionId !== "string") {
+        return null;
+      }
+
+      const spawnedAt = new Date(parsed.spawnedAt);
+      if (Number.isNaN(spawnedAt.getTime())) {
+        return null;
+      }
+
+      return {
+        spawnedAt,
+        sessionId: parsed.sessionId,
+      };
+    } catch {
+      return null;
+    }
+  }
+}

apps/orchestrator/src/api/agents/agents-killswitch.controller.spec.ts

@@ -5,6 +5,9 @@ import { AgentSpawnerService } from "../../spawner/agent-spawner.service";
 import { AgentLifecycleService } from "../../spawner/agent-lifecycle.service";
 import { KillswitchService } from "../../killswitch/killswitch.service";
 import { AgentEventsService } from "./agent-events.service";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentControlService } from "./agent-control.service";
+import { AgentTreeService } from "./agent-tree.service";
 import type { KillAllResult } from "../../killswitch/killswitch.service";
 
 describe("AgentsController - Killswitch Endpoints", () => {
@@ -27,6 +30,20 @@ describe("AgentsController - Killswitch Endpoints", () => {
     subscribe: ReturnType<typeof vi.fn>;
     getInitialSnapshot: ReturnType<typeof vi.fn>;
     createHeartbeat: ReturnType<typeof vi.fn>;
+    getRecentEvents: ReturnType<typeof vi.fn>;
+  };
+  let mockMessagesService: {
+    getMessages: ReturnType<typeof vi.fn>;
+    getReplayMessages: ReturnType<typeof vi.fn>;
+    getMessagesAfter: ReturnType<typeof vi.fn>;
+  };
+  let mockControlService: {
+    injectMessage: ReturnType<typeof vi.fn>;
+    pauseAgent: ReturnType<typeof vi.fn>;
+    resumeAgent: ReturnType<typeof vi.fn>;
+  };
+  let mockTreeService: {
+    getTree: ReturnType<typeof vi.fn>;
   };
 
   beforeEach(() => {
@@ -61,6 +78,23 @@ describe("AgentsController - Killswitch Endpoints", () => {
         timestamp: new Date().toISOString(),
         data: { heartbeat: true },
       }),
+      getRecentEvents: vi.fn().mockReturnValue([]),
+    };
+
+    mockMessagesService = {
+      getMessages: vi.fn(),
+      getReplayMessages: vi.fn().mockResolvedValue([]),
+      getMessagesAfter: vi.fn().mockResolvedValue([]),
+    };
+
+    mockControlService = {
+      injectMessage: vi.fn().mockResolvedValue(undefined),
+      pauseAgent: vi.fn().mockResolvedValue(undefined),
+      resumeAgent: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockTreeService = {
+      getTree: vi.fn().mockResolvedValue([]),
     };
 
     controller = new AgentsController(
@@ -68,7 +102,10 @@ describe("AgentsController - Killswitch Endpoints", () => {
       mockSpawnerService as unknown as AgentSpawnerService,
       mockLifecycleService as unknown as AgentLifecycleService,
       mockKillswitchService as unknown as KillswitchService,
-      mockEventsService as unknown as AgentEventsService
+      mockEventsService as unknown as AgentEventsService,
+      mockMessagesService as unknown as AgentMessagesService,
+      mockControlService as unknown as AgentControlService,
+      mockTreeService as unknown as AgentTreeService
     );
   });
 

apps/orchestrator/src/api/agents/agents.controller.spec.ts

@@ -4,6 +4,9 @@ import { AgentSpawnerService } from "../../spawner/agent-spawner.service";
 import { AgentLifecycleService } from "../../spawner/agent-lifecycle.service";
 import { KillswitchService } from "../../killswitch/killswitch.service";
 import { AgentEventsService } from "./agent-events.service";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentControlService } from "./agent-control.service";
+import { AgentTreeService } from "./agent-tree.service";
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 
 describe("AgentsController", () => {
@@ -30,6 +33,19 @@ describe("AgentsController", () => {
     createHeartbeat: ReturnType<typeof vi.fn>;
     getRecentEvents: ReturnType<typeof vi.fn>;
   };
+  let messagesService: {
+    getMessages: ReturnType<typeof vi.fn>;
+    getReplayMessages: ReturnType<typeof vi.fn>;
+    getMessagesAfter: ReturnType<typeof vi.fn>;
+  };
+  let controlService: {
+    injectMessage: ReturnType<typeof vi.fn>;
+    pauseAgent: ReturnType<typeof vi.fn>;
+    resumeAgent: ReturnType<typeof vi.fn>;
+  };
+  let treeService: {
+    getTree: ReturnType<typeof vi.fn>;
+  };
 
   beforeEach(() => {
     // Create mock services
@@ -69,13 +85,32 @@ describe("AgentsController", () => {
       getRecentEvents: vi.fn().mockReturnValue([]),
     };
 
+    messagesService = {
+      getMessages: vi.fn(),
+      getReplayMessages: vi.fn().mockResolvedValue([]),
+      getMessagesAfter: vi.fn().mockResolvedValue([]),
+    };
+
+    controlService = {
+      injectMessage: vi.fn().mockResolvedValue(undefined),
+      pauseAgent: vi.fn().mockResolvedValue(undefined),
+      resumeAgent: vi.fn().mockResolvedValue(undefined),
+    };
+
+    treeService = {
+      getTree: vi.fn().mockResolvedValue([]),
+    };
+
     // Create controller with mocked services
     controller = new AgentsController(
       queueService as unknown as QueueService,
       spawnerService as unknown as AgentSpawnerService,
       lifecycleService as unknown as AgentLifecycleService,
       killswitchService as unknown as KillswitchService,
-      eventsService as unknown as AgentEventsService
+      eventsService as unknown as AgentEventsService,
+      messagesService as unknown as AgentMessagesService,
+      controlService as unknown as AgentControlService,
+      treeService as unknown as AgentTreeService
     );
   });
 
@@ -87,6 +122,27 @@ describe("AgentsController", () => {
     expect(controller).toBeDefined();
   });
 
+  describe("getAgentTree", () => {
+    it("should return tree entries", async () => {
+      const entries = [
+        {
+          sessionId: "agent-1",
+          parentSessionId: null,
+          status: "running",
+          agentType: "worker",
+          taskSource: "internal",
+          spawnedAt: "2026-03-07T00:00:00.000Z",
+          completedAt: null,
+        },
+      ];
+
+      treeService.getTree.mockResolvedValue(entries);
+
+      await expect(controller.getAgentTree()).resolves.toEqual(entries);
+      expect(treeService.getTree).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("listAgents", () => {
     it("should return empty array when no agents exist", () => {
       // Arrange
@@ -365,6 +421,93 @@ describe("AgentsController", () => {
     });
   });
 
+  describe("agent control endpoints", () => {
+    const agentId = "0b64079f-4487-42b9-92eb-cf8ea0042a64";
+
+    it("should inject an operator message", async () => {
+      const req = { apiKey: "control-key" };
+
+      const result = await controller.injectAgentMessage(
+        agentId,
+        { message: "pause and summarize" },
+        req
+      );
+
+      expect(controlService.injectMessage).toHaveBeenCalledWith(
+        agentId,
+        "control-key",
+        "pause and summarize"
+      );
+      expect(result).toEqual({ message: `Message injected into agent ${agentId}` });
+    });
+
+    it("should default operator id when request api key is missing", async () => {
+      await controller.injectAgentMessage(agentId, { message: "continue" }, {});
+
+      expect(controlService.injectMessage).toHaveBeenCalledWith(agentId, "operator", "continue");
+    });
+
+    it("should pause an agent", async () => {
+      const result = await controller.pauseAgent(agentId, {}, { apiKey: "ops-user" });
+
+      expect(controlService.pauseAgent).toHaveBeenCalledWith(agentId, "ops-user");
+      expect(result).toEqual({ message: `Agent ${agentId} paused` });
+    });
+
+    it("should resume an agent", async () => {
+      const result = await controller.resumeAgent(agentId, {}, { apiKey: "ops-user" });
+
+      expect(controlService.resumeAgent).toHaveBeenCalledWith(agentId, "ops-user");
+      expect(result).toEqual({ message: `Agent ${agentId} resumed` });
+    });
+  });
+
+  describe("getAgentMessages", () => {
+    it("should return paginated message history", async () => {
+      const agentId = "0b64079f-4487-42b9-92eb-cf8ea0042a64";
+      const query = {
+        limit: 25,
+        skip: 10,
+      };
+
+      const response = {
+        messages: [
+          {
+            id: "msg-1",
+            sessionId: agentId,
+            role: "agent",
+            content: "hello",
+            provider: "internal",
+            timestamp: new Date("2026-03-07T03:00:00.000Z"),
+            metadata: {},
+          },
+        ],
+        total: 101,
+      };
+
+      messagesService.getMessages.mockResolvedValue(response);
+
+      const result = await controller.getAgentMessages(agentId, query);
+
+      expect(messagesService.getMessages).toHaveBeenCalledWith(agentId, 25, 10);
+      expect(result).toEqual(response);
+    });
+
+    it("should use default pagination values", async () => {
+      const agentId = "0b64079f-4487-42b9-92eb-cf8ea0042a64";
+      const query = {
+        limit: 50,
+        skip: 0,
+      };
+
+      messagesService.getMessages.mockResolvedValue({ messages: [], total: 0 });
+
+      await controller.getAgentMessages(agentId, query);
+
+      expect(messagesService.getMessages).toHaveBeenCalledWith(agentId, 50, 0);
+    });
+  });
+
   describe("getRecentEvents", () => {
     it("should return recent events with default limit", () => {
       eventsService.getRecentEvents.mockReturnValue([

apps/orchestrator/src/api/agents/agents.controller.ts

@@ -14,7 +14,9 @@ import {
   Sse,
   MessageEvent,
   Query,
+  Request,
 } from "@nestjs/common";
+import type { AgentConversationMessage } from "@prisma/client";
 import { Throttle } from "@nestjs/throttler";
 import { Observable } from "rxjs";
 import { QueueService } from "../../queue/queue.service";
@@ -25,6 +27,13 @@ import { SpawnAgentDto, SpawnAgentResponseDto } from "./dto/spawn-agent.dto";
 import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
 import { OrchestratorThrottlerGuard } from "../../common/guards/throttler.guard";
 import { AgentEventsService } from "./agent-events.service";
+import { GetMessagesQueryDto } from "./dto/get-messages-query.dto";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentControlService } from "./agent-control.service";
+import { AgentTreeService } from "./agent-tree.service";
+import { AgentTreeResponseDto } from "./dto/agent-tree-response.dto";
+import { InjectAgentDto } from "./dto/inject-agent.dto";
+import { PauseAgentDto, ResumeAgentDto } from "./dto/control-agent.dto";
 
 /**
  * Controller for agent management endpoints
@@ -47,7 +56,10 @@ export class AgentsController {
     private readonly spawnerService: AgentSpawnerService,
     private readonly lifecycleService: AgentLifecycleService,
     private readonly killswitchService: KillswitchService,
-    private readonly eventsService: AgentEventsService
+    private readonly eventsService: AgentEventsService,
+    private readonly messagesService: AgentMessagesService,
+    private readonly agentControlService: AgentControlService,
+    private readonly agentTreeService: AgentTreeService
   ) {}
 
   /**
@@ -69,6 +81,7 @@ export class AgentsController {
       // Spawn agent using spawner service
       const spawnResponse = this.spawnerService.spawnAgent({
         taskId: dto.taskId,
+        ...(dto.parentAgentId !== undefined ? { parentAgentId: dto.parentAgentId } : {}),
         agentType: dto.agentType,
         context: dto.context,
       });
@@ -143,6 +156,13 @@ export class AgentsController {
     };
   }
 
+  @Get("tree")
+  @UseGuards(OrchestratorApiKeyGuard)
+  @Throttle({ default: { limit: 200, ttl: 60000 } })
+  async getAgentTree(): Promise<AgentTreeResponseDto[]> {
+    return this.agentTreeService.getTree();
+  }
+
   /**
    * List all agents
    * @returns Array of all agent sessions with their status
@@ -185,6 +205,107 @@ export class AgentsController {
     }
   }
 
+  /**
+   * Get paginated message history for an agent.
+   */
+  @Get(":agentId/messages")
+  @Throttle({ status: { limit: 200, ttl: 60000 } })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getAgentMessages(
+    @Param("agentId", ParseUUIDPipe) agentId: string,
+    @Query() query: GetMessagesQueryDto
+  ): Promise<{
+    messages: AgentConversationMessage[];
+    total: number;
+  }> {
+    return this.messagesService.getMessages(agentId, query.limit, query.skip);
+  }
+
+  /**
+   * Stream per-agent conversation messages as server-sent events (SSE).
+   */
+  @Sse(":agentId/messages/stream")
+  @Throttle({ status: { limit: 200, ttl: 60000 } })
+  streamAgentMessages(@Param("agentId", ParseUUIDPipe) agentId: string): Observable<MessageEvent> {
+    return new Observable<MessageEvent>((subscriber) => {
+      let isClosed = false;
+      let lastSeenTimestamp = new Date();
+      let lastSeenMessageId: string | null = null;
+
+      const emitMessage = (message: AgentConversationMessage): void => {
+        if (isClosed) {
+          return;
+        }
+
+        subscriber.next({
+          data: this.toMessageStreamPayload(message),
+        });
+
+        lastSeenTimestamp = message.timestamp;
+        lastSeenMessageId = message.id;
+      };
+
+      void this.messagesService
+        .getReplayMessages(agentId, 50)
+        .then((messages) => {
+          if (isClosed) {
+            return;
+          }
+
+          messages.forEach((message) => {
+            emitMessage(message);
+          });
+
+          if (messages.length === 0) {
+            lastSeenTimestamp = new Date();
+            lastSeenMessageId = null;
+          }
+        })
+        .catch((error: unknown) => {
+          this.logger.error(
+            `Failed to load replay messages for ${agentId}: ${error instanceof Error ? error.message : String(error)}`
+          );
+          lastSeenTimestamp = new Date();
+          lastSeenMessageId = null;
+        });
+
+      const pollInterval = setInterval(() => {
+        if (isClosed) {
+          return;
+        }
+
+        void this.messagesService
+          .getMessagesAfter(agentId, lastSeenTimestamp, lastSeenMessageId)
+          .then((messages) => {
+            if (isClosed || messages.length === 0) {
+              return;
+            }
+
+            messages.forEach((message) => {
+              emitMessage(message);
+            });
+          })
+          .catch((error: unknown) => {
+            this.logger.error(
+              `Failed to poll messages for ${agentId}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          });
+      }, 1000);
+
+      const heartbeat = setInterval(() => {
+        if (!isClosed) {
+          subscriber.next({ data: { type: "heartbeat" } });
+        }
+      }, 15000);
+
+      return () => {
+        isClosed = true;
+        clearInterval(pollInterval);
+        clearInterval(heartbeat);
+      };
+    });
+  }
+
   /**
    * Get agent status
    * @param agentId Agent ID to query
@@ -269,6 +390,57 @@ export class AgentsController {
     }
   }
 
+  @Post(":agentId/inject")
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @HttpCode(200)
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async injectAgentMessage(
+    @Param("agentId", ParseUUIDPipe) agentId: string,
+    @Body() dto: InjectAgentDto,
+    @Request() req: { apiKey?: string }
+  ): Promise<{ message: string }> {
+    const operatorId = req.apiKey ?? "operator";
+    await this.agentControlService.injectMessage(agentId, operatorId, dto.message);
+
+    return {
+      message: `Message injected into agent ${agentId}`,
+    };
+  }
+
+  @Post(":agentId/pause")
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @HttpCode(200)
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async pauseAgent(
+    @Param("agentId", ParseUUIDPipe) agentId: string,
+    @Body() _dto: PauseAgentDto,
+    @Request() req: { apiKey?: string }
+  ): Promise<{ message: string }> {
+    const operatorId = req.apiKey ?? "operator";
+    await this.agentControlService.pauseAgent(agentId, operatorId);
+
+    return {
+      message: `Agent ${agentId} paused`,
+    };
+  }
+
+  @Post(":agentId/resume")
+  @Throttle({ default: { limit: 10, ttl: 60000 } })
+  @HttpCode(200)
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async resumeAgent(
+    @Param("agentId", ParseUUIDPipe) agentId: string,
+    @Body() _dto: ResumeAgentDto,
+    @Request() req: { apiKey?: string }
+  ): Promise<{ message: string }> {
+    const operatorId = req.apiKey ?? "operator";
+    await this.agentControlService.resumeAgent(agentId, operatorId);
+
+    return {
+      message: `Agent ${agentId} resumed`,
+    };
+  }
+
   /**
    * Kill all active agents
    * @returns Summary of kill operation
@@ -301,4 +473,24 @@ export class AgentsController {
       throw error;
     }
   }
+
+  private toMessageStreamPayload(message: AgentConversationMessage): {
+    messageId: string;
+    sessionId: string;
+    role: string;
+    content: string;
+    provider: string;
+    timestamp: string;
+    metadata: unknown;
+  } {
+    return {
+      messageId: message.id,
+      sessionId: message.sessionId,
+      role: message.role,
+      content: message.content,
+      provider: message.provider,
+      timestamp: message.timestamp.toISOString(),
+      metadata: message.metadata,
+    };
+  }
 }

apps/orchestrator/src/api/agents/agents.module.ts

@@ -6,10 +6,25 @@ import { KillswitchModule } from "../../killswitch/killswitch.module";
 import { ValkeyModule } from "../../valkey/valkey.module";
 import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
 import { AgentEventsService } from "./agent-events.service";
+import { PrismaModule } from "../../prisma/prisma.module";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentControlService } from "./agent-control.service";
+import { AgentTreeService } from "./agent-tree.service";
+import { InternalAgentProvider } from "./internal-agent.provider";
+import { AgentProviderRegistry } from "./agent-provider.registry";
 
 @Module({
-  imports: [QueueModule, SpawnerModule, KillswitchModule, ValkeyModule],
+  imports: [QueueModule, SpawnerModule, KillswitchModule, ValkeyModule, PrismaModule],
   controllers: [AgentsController],
-  providers: [OrchestratorApiKeyGuard, AgentEventsService],
+  providers: [
+    OrchestratorApiKeyGuard,
+    AgentEventsService,
+    AgentMessagesService,
+    AgentControlService,
+    AgentTreeService,
+    InternalAgentProvider,
+    AgentProviderRegistry,
+  ],
+  exports: [InternalAgentProvider, AgentProviderRegistry],
 })
 export class AgentsModule {}

apps/orchestrator/src/api/agents/dto/agent-tree-response.dto.ts

@@ -0,0 +1,9 @@
+export class AgentTreeResponseDto {
+  sessionId!: string;
+  parentSessionId!: string | null;
+  status!: string;
+  agentType!: string | null;
+  taskSource!: string | null;
+  spawnedAt!: string;
+  completedAt!: string | null;
+}

apps/orchestrator/src/api/agents/dto/control-agent.dto.ts

@@ -0,0 +1,3 @@
+export class PauseAgentDto {}
+
+export class ResumeAgentDto {}

apps/orchestrator/src/api/agents/dto/get-messages-query.dto.spec.ts

@@ -0,0 +1,37 @@
+import { plainToInstance } from "class-transformer";
+import { validate } from "class-validator";
+import { describe, expect, it } from "vitest";
+import { GetMessagesQueryDto } from "./get-messages-query.dto";
+
+describe("GetMessagesQueryDto", () => {
+  it("should use defaults when empty", async () => {
+    const dto = plainToInstance(GetMessagesQueryDto, {});
+    const errors = await validate(dto);
+
+    expect(errors).toHaveLength(0);
+    expect(dto.limit).toBe(50);
+    expect(dto.skip).toBe(0);
+  });
+
+  it("should reject limit greater than 200", async () => {
+    const dto = plainToInstance(GetMessagesQueryDto, {
+      limit: 201,
+      skip: 0,
+    });
+    const errors = await validate(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors.some((error) => error.property === "limit")).toBe(true);
+  });
+
+  it("should reject negative skip", async () => {
+    const dto = plainToInstance(GetMessagesQueryDto, {
+      limit: 50,
+      skip: -1,
+    });
+    const errors = await validate(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors.some((error) => error.property === "skip")).toBe(true);
+  });
+});

apps/orchestrator/src/api/agents/dto/get-messages-query.dto.ts

@@ -0,0 +1,17 @@
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, Max, Min } from "class-validator";
+
+export class GetMessagesQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  limit = 50;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(0)
+  skip = 0;
+}

apps/orchestrator/src/api/agents/dto/inject-agent.dto.ts

@@ -0,0 +1,7 @@
+import { IsNotEmpty, IsString } from "class-validator";
+
+export class InjectAgentDto {
+  @IsString()
+  @IsNotEmpty()
+  message!: string;
+}

apps/orchestrator/src/api/agents/dto/spawn-agent.dto.ts

@@ -116,6 +116,10 @@ export class SpawnAgentDto {
   @IsOptional()
   @IsIn(["strict", "standard", "minimal", "custom"])
   gateProfile?: GateProfileType;
+
+  @IsOptional()
+  @IsString()
+  parentAgentId?: string;
 }
 
 /**

apps/orchestrator/src/api/agents/internal-agent.provider.spec.ts

@@ -0,0 +1,216 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentConversationMessage, AgentSessionTree } from "@prisma/client";
+import { AgentControlService } from "./agent-control.service";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentTreeService } from "./agent-tree.service";
+import { InternalAgentProvider } from "./internal-agent.provider";
+
+describe("InternalAgentProvider", () => {
+  let provider: InternalAgentProvider;
+  let messagesService: {
+    getMessages: ReturnType<typeof vi.fn>;
+    getReplayMessages: ReturnType<typeof vi.fn>;
+    getMessagesAfter: ReturnType<typeof vi.fn>;
+  };
+  let controlService: {
+    injectMessage: ReturnType<typeof vi.fn>;
+    pauseAgent: ReturnType<typeof vi.fn>;
+    resumeAgent: ReturnType<typeof vi.fn>;
+    killAgent: ReturnType<typeof vi.fn>;
+  };
+  let treeService: {
+    listSessions: ReturnType<typeof vi.fn>;
+    getSession: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    messagesService = {
+      getMessages: vi.fn(),
+      getReplayMessages: vi.fn(),
+      getMessagesAfter: vi.fn(),
+    };
+
+    controlService = {
+      injectMessage: vi.fn().mockResolvedValue(undefined),
+      pauseAgent: vi.fn().mockResolvedValue(undefined),
+      resumeAgent: vi.fn().mockResolvedValue(undefined),
+      killAgent: vi.fn().mockResolvedValue(undefined),
+    };
+
+    treeService = {
+      listSessions: vi.fn(),
+      getSession: vi.fn(),
+    };
+
+    provider = new InternalAgentProvider(
+      messagesService as unknown as AgentMessagesService,
+      controlService as unknown as AgentControlService,
+      treeService as unknown as AgentTreeService
+    );
+  });
+
+  it("maps paginated sessions", async () => {
+    const sessionEntry: AgentSessionTree = {
+      id: "tree-1",
+      sessionId: "session-1",
+      parentSessionId: "parent-1",
+      provider: "internal",
+      missionId: null,
+      taskId: "task-123",
+      taskSource: "queue",
+      agentType: "worker",
+      status: "running",
+      spawnedAt: new Date("2026-03-07T10:00:00.000Z"),
+      completedAt: null,
+      metadata: { branch: "feat/test" },
+    };
+
+    treeService.listSessions.mockResolvedValue({
+      sessions: [sessionEntry],
+      total: 1,
+      cursor: "next-cursor",
+    });
+
+    const result = await provider.listSessions("cursor-1", 25);
+
+    expect(treeService.listSessions).toHaveBeenCalledWith("cursor-1", 25);
+    expect(result).toEqual({
+      sessions: [
+        {
+          id: "session-1",
+          providerId: "internal",
+          providerType: "internal",
+          label: "task-123",
+          status: "active",
+          parentSessionId: "parent-1",
+          createdAt: new Date("2026-03-07T10:00:00.000Z"),
+          updatedAt: new Date("2026-03-07T10:00:00.000Z"),
+          metadata: { branch: "feat/test" },
+        },
+      ],
+      total: 1,
+      cursor: "next-cursor",
+    });
+  });
+
+  it("returns null for missing session", async () => {
+    treeService.getSession.mockResolvedValue(null);
+
+    const result = await provider.getSession("missing-session");
+
+    expect(treeService.getSession).toHaveBeenCalledWith("missing-session");
+    expect(result).toBeNull();
+  });
+
+  it("maps message history and parses skip cursor", async () => {
+    const message: AgentConversationMessage = {
+      id: "msg-1",
+      sessionId: "session-1",
+      provider: "internal",
+      role: "agent",
+      content: "hello",
+      timestamp: new Date("2026-03-07T10:05:00.000Z"),
+      metadata: { tokens: 42 },
+    };
+
+    messagesService.getMessages.mockResolvedValue({
+      messages: [message],
+      total: 10,
+    });
+
+    const result = await provider.getMessages("session-1", 30, "2");
+
+    expect(messagesService.getMessages).toHaveBeenCalledWith("session-1", 30, 2);
+    expect(result).toEqual([
+      {
+        id: "msg-1",
+        sessionId: "session-1",
+        role: "assistant",
+        content: "hello",
+        timestamp: new Date("2026-03-07T10:05:00.000Z"),
+        metadata: { tokens: 42 },
+      },
+    ]);
+  });
+
+  it("routes control operations through AgentControlService", async () => {
+    const injectResult = await provider.injectMessage("session-1", "new instruction");
+
+    await provider.pauseSession("session-1");
+    await provider.resumeSession("session-1");
+    await provider.killSession("session-1", false);
+
+    expect(controlService.injectMessage).toHaveBeenCalledWith(
+      "session-1",
+      "internal-provider",
+      "new instruction"
+    );
+    expect(injectResult).toEqual({ accepted: true });
+    expect(controlService.pauseAgent).toHaveBeenCalledWith("session-1", "internal-provider");
+    expect(controlService.resumeAgent).toHaveBeenCalledWith("session-1", "internal-provider");
+    expect(controlService.killAgent).toHaveBeenCalledWith("session-1", "internal-provider", false);
+  });
+
+  it("streams replay and incremental messages", async () => {
+    const replayMessage: AgentConversationMessage = {
+      id: "msg-replay",
+      sessionId: "session-1",
+      provider: "internal",
+      role: "agent",
+      content: "replay",
+      timestamp: new Date("2026-03-07T10:00:00.000Z"),
+      metadata: {},
+    };
+    const incrementalMessage: AgentConversationMessage = {
+      id: "msg-live",
+      sessionId: "session-1",
+      provider: "internal",
+      role: "operator",
+      content: "live",
+      timestamp: new Date("2026-03-07T10:00:01.000Z"),
+      metadata: {},
+    };
+
+    messagesService.getReplayMessages.mockResolvedValue([replayMessage]);
+    messagesService.getMessagesAfter
+      .mockResolvedValueOnce([incrementalMessage])
+      .mockResolvedValueOnce([]);
+
+    const iterator = provider.streamMessages("session-1")[Symbol.asyncIterator]();
+
+    const first = await iterator.next();
+    const second = await iterator.next();
+
+    expect(first.done).toBe(false);
+    expect(first.value).toEqual({
+      id: "msg-replay",
+      sessionId: "session-1",
+      role: "assistant",
+      content: "replay",
+      timestamp: new Date("2026-03-07T10:00:00.000Z"),
+      metadata: {},
+    });
+    expect(second.done).toBe(false);
+    expect(second.value).toEqual({
+      id: "msg-live",
+      sessionId: "session-1",
+      role: "user",
+      content: "live",
+      timestamp: new Date("2026-03-07T10:00:01.000Z"),
+      metadata: {},
+    });
+
+    await iterator.return?.();
+
+    expect(messagesService.getReplayMessages).toHaveBeenCalledWith("session-1", 50);
+    expect(messagesService.getMessagesAfter).toHaveBeenCalledWith(
+      "session-1",
+      new Date("2026-03-07T10:00:00.000Z"),
+      "msg-replay"
+    );
+  });
+
+  it("reports provider availability", async () => {
+    await expect(provider.isAvailable()).resolves.toBe(true);
+  });
+});

apps/orchestrator/src/api/agents/internal-agent.provider.ts

@@ -0,0 +1,218 @@
+import { Injectable } from "@nestjs/common";
+import type {
+  AgentMessage,
+  AgentMessageRole,
+  AgentSession,
+  AgentSessionList,
+  AgentSessionStatus,
+  IAgentProvider,
+  InjectResult,
+} from "@mosaic/shared";
+import type { AgentConversationMessage, AgentSessionTree } from "@prisma/client";
+import { AgentControlService } from "./agent-control.service";
+import { AgentMessagesService } from "./agent-messages.service";
+import { AgentTreeService } from "./agent-tree.service";
+
+const DEFAULT_SESSION_LIMIT = 50;
+const DEFAULT_MESSAGE_LIMIT = 50;
+const MAX_MESSAGE_LIMIT = 200;
+const STREAM_POLL_INTERVAL_MS = 1000;
+const INTERNAL_OPERATOR_ID = "internal-provider";
+
+@Injectable()
+export class InternalAgentProvider implements IAgentProvider {
+  readonly providerId = "internal";
+  readonly providerType = "internal";
+  readonly displayName = "Internal Orchestrator";
+
+  constructor(
+    private readonly messagesService: AgentMessagesService,
+    private readonly controlService: AgentControlService,
+    private readonly treeService: AgentTreeService
+  ) {}
+
+  async listSessions(cursor?: string, limit = DEFAULT_SESSION_LIMIT): Promise<AgentSessionList> {
+    const {
+      sessions,
+      total,
+      cursor: nextCursor,
+    } = await this.treeService.listSessions(cursor, limit);
+
+    return {
+      sessions: sessions.map((session) => this.toAgentSession(session)),
+      total,
+      ...(nextCursor !== undefined ? { cursor: nextCursor } : {}),
+    };
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | null> {
+    const session = await this.treeService.getSession(sessionId);
+    return session ? this.toAgentSession(session) : null;
+  }
+
+  async getMessages(
+    sessionId: string,
+    limit = DEFAULT_MESSAGE_LIMIT,
+    before?: string
+  ): Promise<AgentMessage[]> {
+    const safeLimit = this.normalizeMessageLimit(limit);
+    const skip = this.parseSkip(before);
+
+    const result = await this.messagesService.getMessages(sessionId, safeLimit, skip);
+    return result.messages.map((message) => this.toAgentMessage(message));
+  }
+
+  async injectMessage(sessionId: string, content: string): Promise<InjectResult> {
+    await this.controlService.injectMessage(sessionId, INTERNAL_OPERATOR_ID, content);
+
+    return {
+      accepted: true,
+    };
+  }
+
+  async pauseSession(sessionId: string): Promise<void> {
+    await this.controlService.pauseAgent(sessionId, INTERNAL_OPERATOR_ID);
+  }
+
+  async resumeSession(sessionId: string): Promise<void> {
+    await this.controlService.resumeAgent(sessionId, INTERNAL_OPERATOR_ID);
+  }
+
+  async killSession(sessionId: string, force = true): Promise<void> {
+    await this.controlService.killAgent(sessionId, INTERNAL_OPERATOR_ID, force);
+  }
+
+  async *streamMessages(sessionId: string): AsyncIterable<AgentMessage> {
+    const replayMessages = await this.messagesService.getReplayMessages(
+      sessionId,
+      DEFAULT_MESSAGE_LIMIT
+    );
+
+    let lastSeenTimestamp = new Date();
+    let lastSeenMessageId: string | null = null;
+
+    for (const message of replayMessages) {
+      yield this.toAgentMessage(message);
+      lastSeenTimestamp = message.timestamp;
+      lastSeenMessageId = message.id;
+    }
+
+    for (;;) {
+      const newMessages = await this.messagesService.getMessagesAfter(
+        sessionId,
+        lastSeenTimestamp,
+        lastSeenMessageId
+      );
+
+      for (const message of newMessages) {
+        yield this.toAgentMessage(message);
+        lastSeenTimestamp = message.timestamp;
+        lastSeenMessageId = message.id;
+      }
+
+      await this.delay(STREAM_POLL_INTERVAL_MS);
+    }
+  }
+
+  isAvailable(): Promise<boolean> {
+    return Promise.resolve(true);
+  }
+
+  private toAgentSession(session: AgentSessionTree): AgentSession {
+    const metadata = this.toMetadata(session.metadata);
+
+    return {
+      id: session.sessionId,
+      providerId: this.providerId,
+      providerType: this.providerType,
+      ...(session.taskId !== null ? { label: session.taskId } : {}),
+      status: this.toSessionStatus(session.status),
+      ...(session.parentSessionId !== null ? { parentSessionId: session.parentSessionId } : {}),
+      createdAt: session.spawnedAt,
+      updatedAt: session.completedAt ?? session.spawnedAt,
+      ...(metadata !== undefined ? { metadata } : {}),
+    };
+  }
+
+  private toAgentMessage(message: AgentConversationMessage): AgentMessage {
+    const metadata = this.toMetadata(message.metadata);
+
+    return {
+      id: message.id,
+      sessionId: message.sessionId,
+      role: this.toMessageRole(message.role),
+      content: message.content,
+      timestamp: message.timestamp,
+      ...(metadata !== undefined ? { metadata } : {}),
+    };
+  }
+
+  private toSessionStatus(status: string): AgentSessionStatus {
+    switch (status) {
+      case "running":
+        return "active";
+      case "paused":
+        return "paused";
+      case "completed":
+        return "completed";
+      case "failed":
+      case "killed":
+        return "failed";
+      case "spawning":
+      default:
+        return "idle";
+    }
+  }
+
+  private toMessageRole(role: string): AgentMessageRole {
+    switch (role) {
+      case "agent":
+      case "assistant":
+        return "assistant";
+      case "system":
+        return "system";
+      case "tool":
+        return "tool";
+      case "operator":
+      case "user":
+      default:
+        return "user";
+    }
+  }
+
+  private normalizeMessageLimit(limit: number): number {
+    const normalized = Number.isFinite(limit) ? Math.trunc(limit) : DEFAULT_MESSAGE_LIMIT;
+    if (normalized < 1) {
+      return 1;
+    }
+
+    return Math.min(normalized, MAX_MESSAGE_LIMIT);
+  }
+
+  private parseSkip(before?: string): number {
+    if (!before) {
+      return 0;
+    }
+
+    const parsed = Number.parseInt(before, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+      return 0;
+    }
+
+    return parsed;
+  }
+
+  private toMetadata(value: unknown): Record<string, unknown> | undefined {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+
+    return undefined;
+  }
+
+  private async delay(ms: number): Promise<void> {
+    await new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+}

apps/orchestrator/src/api/mission-control/dto/get-mission-control-messages-query.dto.ts

@@ -0,0 +1,15 @@
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsString, Max, Min } from "class-validator";
+
+export class GetMissionControlMessagesQueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  limit?: number;
+
+  @IsOptional()
+  @IsString()
+  before?: string;
+}

apps/orchestrator/src/api/mission-control/dto/kill-session.dto.ts

@@ -0,0 +1,7 @@
+import { IsBoolean, IsOptional } from "class-validator";
+
+export class KillSessionDto {
+  @IsOptional()
+  @IsBoolean()
+  force?: boolean;
+}

apps/orchestrator/src/api/mission-control/mission-control.controller.ts

@@ -0,0 +1,183 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Header,
+  HttpCode,
+  MessageEvent,
+  Param,
+  Post,
+  Query,
+  Request,
+  Sse,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from "@nestjs/common";
+import type { AgentMessage, AgentSession, InjectResult } from "@mosaic/shared";
+import { Observable } from "rxjs";
+import { AuthGuard } from "../../auth/guards/auth.guard";
+import { InjectAgentDto } from "../agents/dto/inject-agent.dto";
+import { GetMissionControlMessagesQueryDto } from "./dto/get-mission-control-messages-query.dto";
+import { KillSessionDto } from "./dto/kill-session.dto";
+import { MissionControlService } from "./mission-control.service";
+
+const DEFAULT_OPERATOR_ID = "mission-control";
+
+interface MissionControlRequest {
+  user?: {
+    id?: string;
+  };
+}
+
+@Controller("api/mission-control")
+@UseGuards(AuthGuard)
+export class MissionControlController {
+  constructor(private readonly missionControlService: MissionControlService) {}
+
+  @Get("sessions")
+  async listSessions(): Promise<{ sessions: AgentSession[] }> {
+    const sessions = await this.missionControlService.listSessions();
+    return { sessions };
+  }
+
+  @Get("sessions/:sessionId")
+  getSession(@Param("sessionId") sessionId: string): Promise<AgentSession> {
+    return this.missionControlService.getSession(sessionId);
+  }
+
+  @Get("sessions/:sessionId/messages")
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getMessages(
+    @Param("sessionId") sessionId: string,
+    @Query() query: GetMissionControlMessagesQueryDto
+  ): Promise<{ messages: AgentMessage[] }> {
+    const messages = await this.missionControlService.getMessages(
+      sessionId,
+      query.limit,
+      query.before
+    );
+
+    return { messages };
+  }
+
+  @Post("sessions/:sessionId/inject")
+  @HttpCode(200)
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  injectMessage(
+    @Param("sessionId") sessionId: string,
+    @Body() dto: InjectAgentDto,
+    @Request() req: MissionControlRequest
+  ): Promise<InjectResult> {
+    return this.missionControlService.injectMessage(
+      sessionId,
+      dto.message,
+      this.resolveOperatorId(req)
+    );
+  }
+
+  @Post("sessions/:sessionId/pause")
+  @HttpCode(200)
+  async pauseSession(
+    @Param("sessionId") sessionId: string,
+    @Request() req: MissionControlRequest
+  ): Promise<{ message: string }> {
+    await this.missionControlService.pauseSession(sessionId, this.resolveOperatorId(req));
+
+    return { message: `Session ${sessionId} paused` };
+  }
+
+  @Post("sessions/:sessionId/resume")
+  @HttpCode(200)
+  async resumeSession(
+    @Param("sessionId") sessionId: string,
+    @Request() req: MissionControlRequest
+  ): Promise<{ message: string }> {
+    await this.missionControlService.resumeSession(sessionId, this.resolveOperatorId(req));
+
+    return { message: `Session ${sessionId} resumed` };
+  }
+
+  @Post("sessions/:sessionId/kill")
+  @HttpCode(200)
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async killSession(
+    @Param("sessionId") sessionId: string,
+    @Body() dto: KillSessionDto,
+    @Request() req: MissionControlRequest
+  ): Promise<{ message: string }> {
+    await this.missionControlService.killSession(
+      sessionId,
+      dto.force ?? true,
+      this.resolveOperatorId(req)
+    );
+
+    return { message: `Session ${sessionId} killed` };
+  }
+
+  @Sse("sessions/:sessionId/stream")
+  @Header("Content-Type", "text/event-stream")
+  @Header("Cache-Control", "no-cache")
+  streamSessionMessages(@Param("sessionId") sessionId: string): Observable<MessageEvent> {
+    return new Observable<MessageEvent>((subscriber) => {
+      let isClosed = false;
+      let iterator: AsyncIterator<AgentMessage> | null = null;
+
+      void this.missionControlService
+        .streamMessages(sessionId)
+        .then(async (stream) => {
+          iterator = stream[Symbol.asyncIterator]();
+
+          for (;;) {
+            if (isClosed) {
+              break;
+            }
+
+            const next = (await iterator.next()) as { done: boolean; value: AgentMessage };
+            if (next.done) {
+              break;
+            }
+
+            subscriber.next({
+              data: this.toStreamPayload(next.value),
+            });
+          }
+
+          subscriber.complete();
+        })
+        .catch((error: unknown) => {
+          subscriber.error(error);
+        });
+
+      return () => {
+        isClosed = true;
+        void iterator?.return?.();
+      };
+    });
+  }
+
+  private resolveOperatorId(req: MissionControlRequest): string {
+    const operatorId = req.user?.id;
+    return typeof operatorId === "string" && operatorId.length > 0
+      ? operatorId
+      : DEFAULT_OPERATOR_ID;
+  }
+
+  private toStreamPayload(message: AgentMessage): {
+    id: string;
+    sessionId: string;
+    role: string;
+    content: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+  } {
+    return {
+      id: message.id,
+      sessionId: message.sessionId,
+      role: message.role,
+      content: message.content,
+      timestamp: message.timestamp.toISOString(),
+      ...(message.metadata !== undefined ? { metadata: message.metadata } : {}),
+    };
+  }
+}

apps/orchestrator/src/api/mission-control/mission-control.module.ts

@@ -0,0 +1,13 @@
+import { Module } from "@nestjs/common";
+import { AgentsModule } from "../agents/agents.module";
+import { AuthModule } from "../../auth/auth.module";
+import { PrismaModule } from "../../prisma/prisma.module";
+import { MissionControlController } from "./mission-control.controller";
+import { MissionControlService } from "./mission-control.service";
+
+@Module({
+  imports: [AgentsModule, AuthModule, PrismaModule],
+  controllers: [MissionControlController],
+  providers: [MissionControlService],
+})
+export class MissionControlModule {}

apps/orchestrator/src/api/mission-control/mission-control.service.spec.ts

@@ -0,0 +1,213 @@
+import { NotFoundException } from "@nestjs/common";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentMessage, AgentSession, IAgentProvider, InjectResult } from "@mosaic/shared";
+import type { PrismaService } from "../../prisma/prisma.service";
+import { AgentProviderRegistry } from "../agents/agent-provider.registry";
+import { MissionControlService } from "./mission-control.service";
+
+type MockProvider = IAgentProvider & {
+  listSessions: ReturnType<typeof vi.fn>;
+  getSession: ReturnType<typeof vi.fn>;
+  getMessages: ReturnType<typeof vi.fn>;
+  injectMessage: ReturnType<typeof vi.fn>;
+  pauseSession: ReturnType<typeof vi.fn>;
+  resumeSession: ReturnType<typeof vi.fn>;
+  killSession: ReturnType<typeof vi.fn>;
+  streamMessages: ReturnType<typeof vi.fn>;
+};
+
+const emptyMessageStream = async function* (): AsyncIterable<AgentMessage> {
+  return;
+};
+
+const createProvider = (providerId = "internal"): MockProvider => ({
+  providerId,
+  providerType: providerId,
+  displayName: providerId,
+  listSessions: vi.fn().mockResolvedValue({ sessions: [], total: 0 }),
+  getSession: vi.fn().mockResolvedValue(null),
+  getMessages: vi.fn().mockResolvedValue([]),
+  injectMessage: vi.fn().mockResolvedValue({ accepted: true } as InjectResult),
+  pauseSession: vi.fn().mockResolvedValue(undefined),
+  resumeSession: vi.fn().mockResolvedValue(undefined),
+  killSession: vi.fn().mockResolvedValue(undefined),
+  streamMessages: vi.fn().mockReturnValue(emptyMessageStream()),
+  isAvailable: vi.fn().mockResolvedValue(true),
+});
+
+describe("MissionControlService", () => {
+  let service: MissionControlService;
+  let registry: {
+    listAllSessions: ReturnType<typeof vi.fn>;
+    getProviderForSession: ReturnType<typeof vi.fn>;
+  };
+  let prisma: {
+    operatorAuditLog: {
+      create: ReturnType<typeof vi.fn>;
+    };
+  };
+
+  const session: AgentSession = {
+    id: "session-1",
+    providerId: "internal",
+    providerType: "internal",
+    status: "active",
+    createdAt: new Date("2026-03-07T14:00:00.000Z"),
+    updatedAt: new Date("2026-03-07T14:01:00.000Z"),
+  };
+
+  beforeEach(() => {
+    registry = {
+      listAllSessions: vi.fn().mockResolvedValue([session]),
+      getProviderForSession: vi.fn().mockResolvedValue(null),
+    };
+
+    prisma = {
+      operatorAuditLog: {
+        create: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+
+    service = new MissionControlService(
+      registry as unknown as AgentProviderRegistry,
+      prisma as unknown as PrismaService
+    );
+  });
+
+  it("lists sessions from the registry", async () => {
+    await expect(service.listSessions()).resolves.toEqual([session]);
+    expect(registry.listAllSessions).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns a session when it is found", async () => {
+    const provider = createProvider("internal");
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await expect(service.getSession(session.id)).resolves.toEqual(session);
+  });
+
+  it("throws NotFoundException when session lookup fails", async () => {
+    await expect(service.getSession("missing-session")).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it("gets messages from the resolved provider", async () => {
+    const provider = createProvider("openclaw");
+    const messages: AgentMessage[] = [
+      {
+        id: "message-1",
+        sessionId: session.id,
+        role: "assistant",
+        content: "hello",
+        timestamp: new Date("2026-03-07T14:01:00.000Z"),
+      },
+    ];
+
+    provider.getMessages.mockResolvedValue(messages);
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await expect(service.getMessages(session.id, 25, "10")).resolves.toEqual(messages);
+    expect(provider.getMessages).toHaveBeenCalledWith(session.id, 25, "10");
+  });
+
+  it("injects a message and writes an audit log", async () => {
+    const provider = createProvider("internal");
+    const injectResult: InjectResult = { accepted: true, messageId: "msg-1" };
+    provider.injectMessage.mockResolvedValue(injectResult);
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await expect(service.injectMessage(session.id, "ship it", "operator-1")).resolves.toEqual(
+      injectResult
+    );
+
+    expect(provider.injectMessage).toHaveBeenCalledWith(session.id, "ship it");
+    expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+      data: {
+        sessionId: session.id,
+        userId: "operator-1",
+        provider: "internal",
+        action: "inject",
+        content: "ship it",
+        metadata: {
+          payload: { message: "ship it" },
+        },
+      },
+    });
+  });
+
+  it("pauses and resumes using default operator id", async () => {
+    const provider = createProvider("openclaw");
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await service.pauseSession(session.id);
+    await service.resumeSession(session.id);
+
+    expect(provider.pauseSession).toHaveBeenCalledWith(session.id);
+    expect(provider.resumeSession).toHaveBeenCalledWith(session.id);
+    expect(prisma.operatorAuditLog.create).toHaveBeenNthCalledWith(1, {
+      data: {
+        sessionId: session.id,
+        userId: "mission-control",
+        provider: "openclaw",
+        action: "pause",
+        metadata: {
+          payload: {},
+        },
+      },
+    });
+    expect(prisma.operatorAuditLog.create).toHaveBeenNthCalledWith(2, {
+      data: {
+        sessionId: session.id,
+        userId: "mission-control",
+        provider: "openclaw",
+        action: "resume",
+        metadata: {
+          payload: {},
+        },
+      },
+    });
+  });
+
+  it("kills with provided force value and writes audit log", async () => {
+    const provider = createProvider("openclaw");
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await service.killSession(session.id, false, "operator-2");
+
+    expect(provider.killSession).toHaveBeenCalledWith(session.id, false);
+    expect(prisma.operatorAuditLog.create).toHaveBeenCalledWith({
+      data: {
+        sessionId: session.id,
+        userId: "operator-2",
+        provider: "openclaw",
+        action: "kill",
+        metadata: {
+          payload: { force: false },
+        },
+      },
+    });
+  });
+
+  it("resolves provider message stream", async () => {
+    const provider = createProvider("internal");
+    const messageStream = (async function* (): AsyncIterable<AgentMessage> {
+      yield {
+        id: "message-1",
+        sessionId: session.id,
+        role: "assistant",
+        content: "stream",
+        timestamp: new Date("2026-03-07T14:03:00.000Z"),
+      };
+    })();
+
+    provider.streamMessages.mockReturnValue(messageStream);
+    registry.getProviderForSession.mockResolvedValue({ provider, session });
+
+    await expect(service.streamMessages(session.id)).resolves.toBe(messageStream);
+    expect(provider.streamMessages).toHaveBeenCalledWith(session.id);
+  });
+
+  it("does not write audit log when session cannot be resolved", async () => {
+    await expect(service.pauseSession("missing-session")).rejects.toBeInstanceOf(NotFoundException);
+    expect(prisma.operatorAuditLog.create).not.toHaveBeenCalled();
+  });
+});

apps/orchestrator/src/api/mission-control/mission-control.service.ts

@@ -0,0 +1,139 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import type { AgentMessage, AgentSession, IAgentProvider, InjectResult } from "@mosaic/shared";
+import type { Prisma } from "@prisma/client";
+import { PrismaService } from "../../prisma/prisma.service";
+import { AgentProviderRegistry } from "../agents/agent-provider.registry";
+
+type MissionControlAction = "inject" | "pause" | "resume" | "kill";
+
+const DEFAULT_OPERATOR_ID = "mission-control";
+
+@Injectable()
+export class MissionControlService {
+  constructor(
+    private readonly registry: AgentProviderRegistry,
+    private readonly prisma: PrismaService
+  ) {}
+
+  listSessions(): Promise<AgentSession[]> {
+    return this.registry.listAllSessions();
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession> {
+    const resolved = await this.registry.getProviderForSession(sessionId);
+    if (!resolved) {
+      throw new NotFoundException(`Session ${sessionId} not found`);
+    }
+
+    return resolved.session;
+  }
+
+  async getMessages(sessionId: string, limit?: number, before?: string): Promise<AgentMessage[]> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    return provider.getMessages(sessionId, limit, before);
+  }
+
+  async injectMessage(
+    sessionId: string,
+    message: string,
+    operatorId = DEFAULT_OPERATOR_ID
+  ): Promise<InjectResult> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    const result = await provider.injectMessage(sessionId, message);
+
+    await this.writeOperatorAuditLog({
+      sessionId,
+      providerId: provider.providerId,
+      operatorId,
+      action: "inject",
+      content: message,
+      payload: { message },
+    });
+
+    return result;
+  }
+
+  async pauseSession(sessionId: string, operatorId = DEFAULT_OPERATOR_ID): Promise<void> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    await provider.pauseSession(sessionId);
+
+    await this.writeOperatorAuditLog({
+      sessionId,
+      providerId: provider.providerId,
+      operatorId,
+      action: "pause",
+      payload: {},
+    });
+  }
+
+  async resumeSession(sessionId: string, operatorId = DEFAULT_OPERATOR_ID): Promise<void> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    await provider.resumeSession(sessionId);
+
+    await this.writeOperatorAuditLog({
+      sessionId,
+      providerId: provider.providerId,
+      operatorId,
+      action: "resume",
+      payload: {},
+    });
+  }
+
+  async killSession(
+    sessionId: string,
+    force = true,
+    operatorId = DEFAULT_OPERATOR_ID
+  ): Promise<void> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    await provider.killSession(sessionId, force);
+
+    await this.writeOperatorAuditLog({
+      sessionId,
+      providerId: provider.providerId,
+      operatorId,
+      action: "kill",
+      payload: { force },
+    });
+  }
+
+  async streamMessages(sessionId: string): Promise<AsyncIterable<AgentMessage>> {
+    const { provider } = await this.getProviderForSessionOrThrow(sessionId);
+    return provider.streamMessages(sessionId);
+  }
+
+  private async getProviderForSessionOrThrow(
+    sessionId: string
+  ): Promise<{ provider: IAgentProvider; session: AgentSession }> {
+    const resolved = await this.registry.getProviderForSession(sessionId);
+
+    if (!resolved) {
+      throw new NotFoundException(`Session ${sessionId} not found`);
+    }
+
+    return resolved;
+  }
+
+  private toJsonValue(value: Record<string, unknown>): Prisma.InputJsonValue {
+    return value as Prisma.InputJsonValue;
+  }
+
+  private async writeOperatorAuditLog(params: {
+    sessionId: string;
+    providerId: string;
+    operatorId: string;
+    action: MissionControlAction;
+    content?: string;
+    payload: Record<string, unknown>;
+  }): Promise<void> {
+    await this.prisma.operatorAuditLog.create({
+      data: {
+        sessionId: params.sessionId,
+        userId: params.operatorId,
+        provider: params.providerId,
+        action: params.action,
+        ...(params.content !== undefined ? { content: params.content } : {}),
+        metadata: this.toJsonValue({ payload: params.payload }),
+      },
+    });
+  }
+}

apps/orchestrator/src/app.module.ts

@@ -4,7 +4,9 @@ import { BullModule } from "@nestjs/bullmq";
 import { ThrottlerModule } from "@nestjs/throttler";
 import { HealthModule } from "./api/health/health.module";
 import { AgentsModule } from "./api/agents/agents.module";
+import { MissionControlModule } from "./api/mission-control/mission-control.module";
 import { QueueApiModule } from "./api/queue/queue-api.module";
+import { AgentProvidersModule } from "./api/agent-providers/agent-providers.module";
 import { CoordinatorModule } from "./coordinator/coordinator.module";
 import { BudgetModule } from "./budget/budget.module";
 import { CIModule } from "./ci";
@@ -51,6 +53,8 @@ import { orchestratorConfig } from "./config/orchestrator.config";
     ]),
     HealthModule,
     AgentsModule,
+    AgentProvidersModule,
+    MissionControlModule,
     QueueApiModule,
     CoordinatorModule,
     BudgetModule,

apps/orchestrator/src/auth/auth.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { OrchestratorApiKeyGuard } from "../common/guards/api-key.guard";
+import { AuthGuard } from "./guards/auth.guard";
+
+@Module({
+  providers: [OrchestratorApiKeyGuard, AuthGuard],
+  exports: [AuthGuard],
+})
+export class AuthModule {}

apps/orchestrator/src/auth/guards/auth.guard.ts

@@ -0,0 +1,11 @@
+import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
+import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(private readonly apiKeyGuard: OrchestratorApiKeyGuard) {}
+
+  canActivate(context: ExecutionContext): boolean | Promise<boolean> {
+    return this.apiKeyGuard.canActivate(context);
+  }
+}

apps/orchestrator/src/prisma/prisma.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from "@nestjs/common";
+import { PrismaService } from "./prisma.service";
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}

apps/orchestrator/src/prisma/prisma.service.ts

@@ -0,0 +1,26 @@
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from "@nestjs/common";
+import { PrismaClient } from "@prisma/client";
+
+/**
+ * Lightweight Prisma service for orchestrator ingestion persistence.
+ */
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(PrismaService.name);
+
+  constructor() {
+    super({
+      log: process.env.NODE_ENV === "development" ? ["warn", "error"] : ["error"],
+    });
+  }
+
+  async onModuleInit(): Promise<void> {
+    await this.$connect();
+    this.logger.log("Database connection established");
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.$disconnect();
+    this.logger.log("Database connection closed");
+  }
+}

apps/orchestrator/src/spawner/agent-lifecycle.service.ts

@@ -1,6 +1,7 @@
-import { Injectable, Logger, Inject, forwardRef } from "@nestjs/common";
+import { Injectable, Logger, Inject, Optional, forwardRef } from "@nestjs/common";
 import { ValkeyService } from "../valkey/valkey.service";
 import { AgentSpawnerService } from "./agent-spawner.service";
+import { AgentIngestionService } from "../agent-ingestion/agent-ingestion.service";
 import type { AgentState, AgentStatus, AgentEvent } from "../valkey/types";
 import { isValidAgentTransition } from "../valkey/types/state.types";
 
@@ -32,7 +33,8 @@ export class AgentLifecycleService {
   constructor(
     private readonly valkeyService: ValkeyService,
     @Inject(forwardRef(() => AgentSpawnerService))
-    private readonly spawnerService: AgentSpawnerService
+    private readonly spawnerService: AgentSpawnerService,
+    @Optional() private readonly agentIngestionService?: AgentIngestionService
   ) {
     this.logger.log("AgentLifecycleService initialized");
   }
@@ -55,6 +57,25 @@ export class AgentLifecycleService {
     return createdState;
   }
 
+  private async recordLifecycleIngestion(
+    agentId: string,
+    event: "started" | "completed" | "failed" | "killed",
+    record: (ingestionService: AgentIngestionService) => Promise<void>
+  ): Promise<void> {
+    if (!this.agentIngestionService) {
+      return;
+    }
+
+    try {
+      await record(this.agentIngestionService);
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(
+        `Failed to record agent ${event} ingestion for ${agentId}: ${errorMessage}`
+      );
+    }
+  }
+
   /**
    * Acquire a per-agent mutex to serialize state transitions.
    * Uses promise chaining: each caller chains onto the previous lock,
@@ -118,6 +139,10 @@ export class AgentLifecycleService {
       // Emit event
       await this.publishStateChangeEvent("agent.running", updatedState);
 
+      await this.recordLifecycleIngestion(agentId, "started", (ingestionService) =>
+        ingestionService.recordAgentStarted(agentId)
+      );
+
       this.logger.log(`Agent ${agentId} transitioned to running`);
       return updatedState;
     });
@@ -155,6 +180,10 @@ export class AgentLifecycleService {
       // Emit event
       await this.publishStateChangeEvent("agent.completed", updatedState);
 
+      await this.recordLifecycleIngestion(agentId, "completed", (ingestionService) =>
+        ingestionService.recordAgentCompleted(agentId)
+      );
+
       // Schedule session cleanup
       this.spawnerService.scheduleSessionCleanup(agentId);
 
@@ -192,6 +221,10 @@ export class AgentLifecycleService {
       // Emit event
       await this.publishStateChangeEvent("agent.failed", updatedState, error);
 
+      await this.recordLifecycleIngestion(agentId, "failed", (ingestionService) =>
+        ingestionService.recordAgentFailed(agentId, error)
+      );
+
       // Schedule session cleanup
       this.spawnerService.scheduleSessionCleanup(agentId);
 
@@ -228,6 +261,10 @@ export class AgentLifecycleService {
       // Emit event
       await this.publishStateChangeEvent("agent.killed", updatedState);
 
+      await this.recordLifecycleIngestion(agentId, "killed", (ingestionService) =>
+        ingestionService.recordAgentKilled(agentId)
+      );
+
       // Schedule session cleanup
       this.spawnerService.scheduleSessionCleanup(agentId);
 

apps/orchestrator/src/spawner/agent-spawner.service.ts

@@ -1,4 +1,11 @@
-import { Injectable, Logger, HttpException, HttpStatus, OnModuleDestroy } from "@nestjs/common";
+import {
+  Injectable,
+  Logger,
+  HttpException,
+  HttpStatus,
+  OnModuleDestroy,
+  Optional,
+} from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import Anthropic from "@anthropic-ai/sdk";
 import { randomUUID } from "crypto";
@@ -8,6 +15,7 @@ import {
   AgentSession,
   AgentType,
 } from "./types/agent-spawner.types";
+import { AgentIngestionService } from "../agent-ingestion/agent-ingestion.service";
 
 /**
  * Default delay in milliseconds before cleaning up sessions after terminal states
@@ -30,7 +38,10 @@ export class AgentSpawnerService implements OnModuleDestroy {
   private readonly sessionCleanupDelayMs: number;
   private readonly cleanupTimers = new Map<string, NodeJS.Timeout>();
 
-  constructor(private readonly configService: ConfigService) {
+  constructor(
+    private readonly configService: ConfigService,
+    @Optional() private readonly agentIngestionService?: AgentIngestionService
+  ) {
     const configuredProvider = this.configService.get<string>("orchestrator.aiProvider");
     this.aiProvider = this.normalizeAiProvider(configuredProvider);
 
@@ -98,6 +109,25 @@ export class AgentSpawnerService implements OnModuleDestroy {
     this.cleanupTimers.clear();
   }
 
+  private recordSpawnedAgentIngestion(agentId: string, request: SpawnAgentRequest): void {
+    if (!this.agentIngestionService) {
+      return;
+    }
+
+    void this.agentIngestionService
+      .recordAgentSpawned(
+        agentId,
+        request.parentAgentId,
+        undefined,
+        request.taskId,
+        request.agentType
+      )
+      .catch((error: unknown) => {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logger.error(`Failed to record spawned ingestion for ${agentId}: ${errorMessage}`);
+      });
+  }
+
   /**
    * Spawn a new agent with the given configuration
    * @param request Agent spawn request
@@ -130,6 +160,8 @@ export class AgentSpawnerService implements OnModuleDestroy {
     // Store session
     this.sessions.set(agentId, session);
 
+    this.recordSpawnedAgentIngestion(agentId, request);
+
     this.logger.log(`Agent spawned successfully: ${agentId} (type: ${request.agentType})`);
 
     // NOTE: Actual Claude SDK integration will be implemented in next iteration (see issue #TBD)

apps/orchestrator/src/spawner/spawner.module.ts

@@ -3,9 +3,10 @@ import { AgentSpawnerService } from "./agent-spawner.service";
 import { AgentLifecycleService } from "./agent-lifecycle.service";
 import { DockerSandboxService } from "./docker-sandbox.service";
 import { ValkeyModule } from "../valkey/valkey.module";
+import { AgentIngestionModule } from "../agent-ingestion/agent-ingestion.module";
 
 @Module({
-  imports: [ValkeyModule],
+  imports: [ValkeyModule, AgentIngestionModule],
   providers: [AgentSpawnerService, AgentLifecycleService, DockerSandboxService],
   exports: [AgentSpawnerService, AgentLifecycleService, DockerSandboxService],
 })

apps/orchestrator/src/spawner/types/agent-spawner.types.ts

@@ -40,6 +40,8 @@ export interface SpawnAgentOptions {
 export interface SpawnAgentRequest {
   /** Unique task identifier */
   taskId: string;
+  /** Optional parent session identifier for subagent lineage */
+  parentAgentId?: string;
   /** Type of agent to spawn */
   agentType: AgentType;
   /** Context for task execution */

apps/orchestrator/vitest.config.ts

@@ -4,6 +4,7 @@ export default defineConfig({
   test: {
     globals: true,
     environment: "node",
+    setupFiles: ["reflect-metadata"],
     exclude: ["**/node_modules/**", "**/dist/**", "**/tests/integration/**"],
     include: ["src/**/*.spec.ts", "src/**/*.test.ts"],
     coverage: {

docs/MISSION-MANIFEST.md

@@ -5,64 +5,67 @@
 
 ## Mission
 
-**ID:** ms22-p2-named-agent-fleet-20260304  
+**ID:** ms22-p2-named-agent-fleet-20260304
-**Statement:** Implement named agent fleet (jarvis, builder, medic) with per-agent personalities, model assignments, Discord channel routing, and WebUI selector.  
+**Statement:** Implement named agent fleet (jarvis, builder, medic) with per-agent personalities, model assignments, Discord channel routing, and WebUI selector.
-**PRD:** `docs/PRD-MS22-P2-AGENT-FLEET.md`  
+**PRD:** `docs/PRD-MS22-P2-AGENT-FLEET.md`
-**Phase:** Execution  
+**Phase:** Completion
-**Status:** in-progress  
+**Status:** completed
-**Last Updated:** 2026-03-04
+**Last Updated:** 2026-03-05
 
 ## Success Criteria
 
-1. AgentTemplate and UserAgent tables exist and are seeded with jarvis/builder/medic
+1. ✅ AgentTemplate and UserAgent tables exist and are seeded with jarvis/builder/medic
-2. Admin CRUD endpoints at `/admin/agent-templates` work and are guarded
+2. ✅ Admin CRUD endpoints at `/admin/agent-templates` work and are guarded
-3. User agent CRUD endpoints allow per-user agent customization
+3. ✅ User agent CRUD endpoints allow per-user agent customization
-4. Chat proxy routes messages to correct agent by name
+4. ✅ Chat proxy routes messages to correct agent by name
-5. Discord channel → agent routing maps #jarvis/#builder/#medic-alerts
+5. ✅ Discord channel → agent routing maps #jarvis/#builder/#medic-alerts
-6. WebUI shows agent selector and connects to correct agent
+6. ✅ WebUI shows agent selector and connects to correct agent
-7. All CI gates green
+7. ✅ All CI gates green
 
 ## Milestones
 
-| #   | ID            | Name          | Status     | Tasks          | Notes                 |
+| #   | ID            | Name          | Status  | Tasks                  | Notes                       |
-| --- | ------------- | ------------- | ---------- | -------------- | --------------------- |
+| --- | ------------- | ------------- | ------- | ---------------------- | --------------------------- |
-| 1   | schema-seed   | Schema+Seed   | ✅ done    | P2-001, P2-002 | PRs #675, #677 merged |
+| 1   | schema-seed   | Schema+Seed   | ✅ done | P2-001, P2-002         | PRs #675, #677 merged       |
-| 2   | admin-crud    | Admin CRUD    | ✅ done    | P2-003         | PR #678 merged        |
+| 2   | admin-crud    | Admin CRUD    | ✅ done | P2-003                 | PR #678 merged              |
-| 3   | user-crud     | User CRUD     | ✅ done    | P2-004         | PR #682 merged        |
+| 3   | user-crud     | User CRUD     | ✅ done | P2-004                 | PR #682 merged              |
-| 4   | agent-routing | Agent Routing | ⬜ pending | P2-005, P2-006 | Depends on M3         |
+| 4   | agent-routing | Agent Routing | ✅ done | P2-005, P2-006         | PR #684 merged              |
-| 5   | discord-ui    | Discord+UI    | ⬜ pending | P2-007, P2-008 | Depends on M4         |
+| 5   | discord-ui    | Discord+UI    | ✅ done | P2-007, P2-008, P2-009 | PRs #685, #687, #688 merged |
-| 6   | verification  | Verification  | ⬜ pending | P2-009, P2-010 | Final gate            |
+| 6   | verification  | Verification  | ✅ done | P2-010                 | All CI gates green          |
 
 ## Task Summary
 
 See `docs/TASKS.md` — MS22 Phase 2 section for full task details.
 
-| Task                    | Status         | PR   | Notes                          |
+| Task                    | Status  | PR   | Notes                          |
-| ----------------------- | -------------- | ---- | ------------------------------ |
+| ----------------------- | ------- | ---- | ------------------------------ |
-| P2-001 Schema           | ✅ done        | #675 | AgentTemplate + UserAgent      |
+| P2-001 Schema           | ✅ done | #675 | AgentTemplate + UserAgent      |
-| P2-002 Seed             | ✅ done        | #677 | jarvis/builder/medic templates |
+| P2-002 Seed             | ✅ done | #677 | jarvis/builder/medic templates |
-| P2-003 Admin CRUD       | ✅ done        | #678 | /admin/agent-templates         |
+| P2-003 Admin CRUD       | ✅ done | #678 | /admin/agent-templates         |
-| P2-004 User CRUD        | ✅ done        | #682 | /api/agents                    |
+| P2-004 User CRUD        | ✅ done | #682 | /api/agents                    |
-| P2-005 Status endpoints | ⬜ not-started | —    |                                |
+| P2-005 Status endpoints | ✅ done | #684 | Agent status API               |
-| P2-006 Chat routing     | ⬜ not-started | —    |                                |
+| P2-006 Chat routing     | ✅ done | #684 | Agent routing in chat proxy    |
-| P2-007 Discord routing  | ⬜ not-started | —    |                                |
+| P2-007 Discord routing  | ✅ done | #688 | Channel → agent routing        |
-| P2-008 WebUI selector   | ⬜ not-started | —    |                                |
+| P2-008 WebUI selector   | ✅ done | #685 | AgentSelector component        |
-| P2-009 Unit tests       | ⬜ not-started | —    |                                |
+| P2-009 Unit tests       | ✅ done | #687 | Agent services tests           |
-| P2-010 E2E verification | ⬜ not-started | —    |                                |
+| P2-010 E2E verification | ✅ done | —    | 3547 tests pass, CI green      |
 
 ## Token Budget
 
-| Phase             | Est      | Used                 |
+| Phase             | Est      | Used     |
-| ----------------- | -------- | -------------------- |
+| ----------------- | -------- | -------- |
-| Schema+Seed+CRUD  | 30K      | ~15K (done directly) |
+| Schema+Seed+CRUD  | 30K      | ~15K     |
-| User CRUD+Routing | 40K      | ~25K                 |
+| User CRUD+Routing | 40K      | ~25K     |
-| Discord+UI        | 30K      | —                    |
+| Discord+UI        | 30K      | ~24K     |
-| Verification      | 10K      | —                    |
+| Verification      | 10K      | ~5K      |
-| **Total**         | **110K** | **~40K**             |
+| **Total**         | **110K** | **~69K** |
 
 ## Session Log
 
-| Date       | Work Done                                                                                                 |
+| Date       | Work Done                                                                                                         |
-| ---------- | --------------------------------------------------------------------------------------------------------- |
+| ---------- | ----------------------------------------------------------------------------------------------------------------- |
-| 2026-03-04 | Session 2: Fixed CI security audit, merged PRs #681, #678, #682. Milestones 1-3 complete (4/6 remaining). |
+| 2026-03-05 | Session 5: Completed P2-010 E2E verification. All 10 tasks done. Mission complete.                                |
-| 2026-03-04 | P2-001..003 shipped; CI fix; postgres rebuilt; mission initialized                                        |
+| 2026-03-05 | Session 4: Completed P2-007 (Discord routing) PR #688. Milestone 5 complete. 9/10 tasks done, only E2E remains.   |
+| 2026-03-05 | Session 3: Completed P2-008 (WebUI agent selector) PR #685. Milestones 1-4 + P2-008 complete (3 tasks remaining). |
+| 2026-03-04 | Session 2: Fixed CI security audit, merged PRs #681, #678, #682. Milestones 1-3 complete (4/6 remaining).         |
+| 2026-03-04 | P2-001..003 shipped; CI fix; postgres rebuilt; mission initialized                                                |

docs/PRD-MS23-mission-control.md

@@ -0,0 +1,555 @@
+# PRD: MS23 — Mission Control Dashboard & Agent Provider Interface
+
+## Metadata
+
+- **Owner:** Jason Woltje
+- **Date:** 2026-03-06
+- **Status:** draft
+- **Mission ID:** ms23-mission-control-20260306
+- **Target Version:** 0.0.23
+- **Roadmap Milestone:** M6 — Orchestration (0.0.6 trajectory)
+- **Depends On:** MS22 Phase 2 (Named Agent Fleet) — COMPLETE
+- **Related Docs:**
+  - `~/src/jarvis-brain/docs/planning/MISSION-CONTROL-UI-PRD.md` (concept origin)
+  - `~/src/jarvis-brain/docs/planning/FLEET-EVOLUTION-PLAN.md`
+  - `docs/PRD-MS22-P2-AGENT-FLEET.md`
+
+---
+
+## Problem Statement
+
+The Mosaic orchestration backend is fully operational: agents spawn, execute tasks, publish lifecycle events via Valkey pub/sub, and can be killed via API. The frontend exposes rudimentary widgets (AgentStatusWidget, OrchestratorEventsWidget) that show aggregate status.
+
+What's missing is **operational visibility and control at the session level**. There is no way to:
+
+1. See what an individual agent is actually saying and doing (conversation stream per agent)
+2. Inject a message into a running agent session without terminating it (barge-in)
+3. Understand the parent/child relationship between orchestrators and their subagents
+4. Connect Mosaic's orchestration layer to external agent runtimes (OpenClaw sessions, Codex ACP, raw PTY agents) through a consistent, extensible interface
+
+Jason operates multiple projects in parallel — multiple orchestrating agents running simultaneously across missions. Today this requires context-switching between terminals, Discord channels, and status widgets. Mission Control solves this.
+
+**Mosaic is designed to be an enterprise-grade, multi-user AI operations platform.** Not every user will use OpenClaw. Not every team will use Codex. Mosaic must provide a plugin adapter interface that allows any agent runtime to integrate with the same orchestration harness, control plane, and UI.
+
+---
+
+## Objectives
+
+1. **Mission Control Dashboard** — Single-pane-of-glass view: N orchestrator panels in a responsive grid, each showing a live agent chat stream with full operator controls
+2. **Per-Agent Conversation Streaming** — Stream individual agent message logs (not just lifecycle events) to the frontend via SSE
+3. **Barge-In / Message Injection** — Operator can inject messages directly into any running agent session with audit trail
+4. **Subagent Tree Tracking** — Agents report parent/child relationships; UI renders the full agent roster as a tree
+5. **Agent Provider Interface (API)** — Formal plugin adapter interface that any agent runtime can implement to integrate with Mosaic's orchestration layer
+6. **OpenClaw Provider Adapter** — Reference implementation of the Agent Provider Interface for OpenClaw ACP sessions
+7. **Operator Controls** — Pause, resume, graceful terminate, hard kill per agent; kill-all panic button
+8. **Audit Trail** — All operator interventions (barge-in, kill, pause) logged with timestamp, user, target, and content
+
+---
+
+## Scope
+
+### In Scope
+
+- Agent conversation log storage and streaming API (per-agent SSE stream of messages)
+- Barge-in endpoint: inject operator message into running agent session
+- Pause / resume agent execution
+- Subagent tree: parent-agent relationship on spawn registration
+- Agent Provider Interface: TypeScript interface + NestJS plugin module
+- OpenClaw adapter: implements Agent Provider Interface for OpenClaw sessions
+- Mission Control page (`/mission-control`) with grid of orchestrator panels
+- OrchestratorPanel component: live chat stream + barge-in input + operator controls
+- Global Agent Roster: tree view sidebar showing all agents + subagents with kill buttons
+- Audit log: UI and API for operator action history
+- Role: `operator` (full control) and `observer` (read-only) applied to all new endpoints
+
+### Out of Scope
+
+- Mobile layout (desktop-first, responsive grid min-width 1200px)
+- Multi-user concurrent barge-in coordination (single operator per session)
+- Historical session replay / time-travel debugging (future milestone)
+- Codex ACP adapter (follow-on after OpenClaw adapter validates interface)
+- Raw PTY adapter (follow-on)
+- Agent-to-agent communication graph visualization (future)
+- Agent marketplace / plugin registry UI (future)
+
+---
+
+## Current State Assessment
+
+### What Exists (Do Not Rebuild)
+
+| Component                | Location                                | Status                           |
+| ------------------------ | --------------------------------------- | -------------------------------- |
+| AgentSpawnerService      | `apps/orchestrator/src/spawner/`        | ✅ Production                    |
+| AgentLifecycleService    | `apps/orchestrator/src/spawner/`        | ✅ Production                    |
+| KillswitchService        | `apps/orchestrator/src/killswitch/`     | ✅ Production                    |
+| AgentEventsService       | `apps/orchestrator/src/api/agents/`     | ✅ SSE lifecycle events          |
+| `GET /agents`            | Orchestrator API                        | ✅ Lists all agents              |
+| `POST /agents/:id/kill`  | Orchestrator API                        | ✅ Kills agent                   |
+| `POST /agents/kill-all`  | Orchestrator API                        | ✅ Kills all                     |
+| `GET /agents/events`     | Orchestrator API                        | ✅ SSE lifecycle stream          |
+| AgentStatusWidget        | `apps/web/src/components/widgets/`      | ✅ Polls agent list              |
+| OrchestratorEventsWidget | `apps/web/src/components/widgets/`      | ✅ SSE lifecycle events          |
+| HUD widget grid          | `apps/web/src/components/hud/`          | ✅ Drag/resize/add/remove        |
+| Chat component           | `apps/web/src/components/chat/`         | ✅ Chat UI exists                |
+| Socket.io                | `apps/api/` (speech.gateway.ts)         | ✅ WebSocket pattern established |
+| CoordinatorIntegration   | `apps/api/src/coordinator-integration/` | ✅ API ↔ Orchestrator bridge     |
+
+### What's Missing (Build This)
+
+| Gap                                              | Priority |
+| ------------------------------------------------ | -------- |
+| Per-agent conversation message log (DB + API)    | P0       |
+| Per-agent SSE message stream                     | P0       |
+| Barge-in endpoint (`POST /agents/:id/inject`)    | P0       |
+| Pause / resume endpoints                         | P1       |
+| Subagent tree (parentAgentId on registration)    | P0       |
+| Agent Provider Interface (plugin API)            | P0       |
+| OpenClaw adapter (implements provider interface) | P1       |
+| Mission Control page (`/mission-control`)        | P0       |
+| OrchestratorPanel component                      | P0       |
+| Global Agent Roster (tree view)                  | P0       |
+| Audit log (DB + API + UI)                        | P1       |
+
+---
+
+## Architecture
+
+### Agent Provider Interface
+
+Mosaic defines a standard contract. Any agent runtime that implements this interface integrates natively with Mission Control.
+
+```typescript
+// packages/shared/src/agent-provider.interface.ts
+
+export interface AgentSession {
+  sessionId: string;
+  parentSessionId?: string; // For subagent tree
+  provider: string; // "internal" | "openclaw" | "codex" | ...
+  status: AgentSessionStatus;
+  taskId?: string;
+  missionId?: string;
+  agentType?: string;
+  spawnedAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type AgentSessionStatus =
+  | "spawning"
+  | "running"
+  | "waiting"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "killed";
+
+export interface AgentMessage {
+  messageId: string;
+  sessionId: string;
+  role: "agent" | "user" | "system" | "operator";
+  content: string;
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IAgentProvider {
+  readonly providerName: string;
+
+  /** List all currently active sessions */
+  listSessions(): Promise<AgentSession[]>;
+
+  /** Get a single session's current state */
+  getSession(sessionId: string): Promise<AgentSession | null>;
+
+  /** Get recent messages for a session */
+  getMessages(sessionId: string, limit?: number): Promise<AgentMessage[]>;
+
+  /** Subscribe to a session's message stream. Returns unsubscribe fn. */
+  subscribeToMessages(sessionId: string, handler: (message: AgentMessage) => void): () => void;
+
+  /** Inject an operator message into a running session (barge-in) */
+  injectMessage(sessionId: string, content: string, operatorId: string): Promise<void>;
+
+  /** Pause a running agent session */
+  pause(sessionId: string): Promise<void>;
+
+  /** Resume a paused agent session */
+  resume(sessionId: string): Promise<void>;
+
+  /** Graceful terminate — allow agent to finish current step */
+  terminate(sessionId: string): Promise<void>;
+
+  /** Hard kill — immediate termination */
+  kill(sessionId: string): Promise<void>;
+}
+```
+
+### Internal Provider
+
+The existing orchestrator's Docker-based agents implement `IAgentProvider` as the "internal" provider. No behavior change — just wraps existing services behind the interface.
+
+### OpenClaw Provider
+
+Connects to an OpenClaw gateway via its REST API:
+
+- `GET /sessions` → `listSessions()`
+- `GET /sessions/:key/history` → `getMessages()`
+- `POST /sessions/:key/send` → `injectMessage()`
+- OpenClaw SSE or polling → `subscribeToMessages()`
+
+Config per workspace in DB (`AgentProvider` table): gateway URL, API token.
+
+### Provider Registry
+
+```typescript
+// apps/api/src/agent-providers/provider-registry.service.ts
+@Injectable()
+export class AgentProviderRegistry {
+  register(provider: IAgentProvider): void;
+  getProvider(name: string): IAgentProvider;
+  getAllProviders(): IAgentProvider[];
+  listAllSessions(): Promise<AgentSession[]>; // Aggregates across all providers
+}
+```
+
+---
+
+## Database Schema
+
+### New Tables
+
+```prisma
+// AgentConversationMessage — stores all agent messages for streaming + history
+model AgentConversationMessage {
+  id          String   @id @default(cuid())
+  sessionId   String                         // matches agentId in orchestrator
+  provider    String   @default("internal")  // "internal" | "openclaw" | ...
+  role        String                         // "agent" | "user" | "system" | "operator"
+  content     String
+  timestamp   DateTime @default(now())
+  metadata    Json     @default("{}")
+
+  @@index([sessionId, timestamp])
+}
+
+// AgentSessionTree — tracks parent/child relationships
+model AgentSessionTree {
+  id              String   @id @default(cuid())
+  sessionId       String   @unique
+  parentSessionId String?
+  provider        String   @default("internal")
+  missionId       String?
+  taskId          String?
+  agentType       String?
+  status          String   @default("spawning")
+  spawnedAt       DateTime @default(now())
+  completedAt     DateTime?
+  metadata        Json     @default("{}")
+
+  @@index([parentSessionId])
+  @@index([missionId])
+}
+
+// AgentProviderConfig — external provider registration per workspace
+model AgentProviderConfig {
+  id          String   @id @default(cuid())
+  workspaceId String
+  name        String                         // "openclaw-prod", "codex-team", ...
+  provider    String                         // "openclaw" | "codex" | ...
+  gatewayUrl  String
+  credentials Json     @default("{}")        // Encrypted via CryptoService
+  isActive    Boolean  @default(true)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@unique([workspaceId, name])
+}
+
+// OperatorAuditLog — all operator interventions
+model OperatorAuditLog {
+  id         String   @id @default(cuid())
+  userId     String
+  sessionId  String
+  provider   String
+  action     String                          // "barge-in" | "kill" | "pause" | "resume" | "kill-all"
+  content    String?                         // For barge-in: message injected
+  metadata   Json     @default("{}")
+  createdAt  DateTime @default(now())
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([createdAt])
+}
+```
+
+---
+
+## API Endpoints
+
+### Orchestrator API — New Endpoints
+
+```
+POST /agents/:agentId/inject       — Barge-in: inject operator message
+POST /agents/:agentId/pause        — Pause agent execution
+POST /agents/:agentId/resume       — Resume paused agent
+GET  /agents/:agentId/messages     — Get message history (paginated)
+GET  /agents/:agentId/messages/stream — SSE: live message stream for this agent
+GET  /agents/tree                  — Full subagent tree (all agents with parent/child)
+```
+
+### Main API — New Endpoints
+
+```
+# Agent Provider Management
+GET    /api/agent-providers                     — List configured providers
+POST   /api/agent-providers                     — Register external provider
+PATCH  /api/agent-providers/:id                 — Update provider config
+DELETE /api/agent-providers/:id                 — Remove provider
+
+# Unified Session View (aggregates all providers)
+GET    /api/mission-control/sessions            — All active sessions (all providers)
+GET    /api/mission-control/sessions/:id        — Single session details
+GET    /api/mission-control/sessions/:id/messages — Message history
+GET    /api/mission-control/sessions/:id/stream   — SSE message stream (proxied)
+POST   /api/mission-control/sessions/:id/inject   — Barge-in (proxied to provider)
+POST   /api/mission-control/sessions/:id/pause    — Pause (proxied)
+POST   /api/mission-control/sessions/:id/resume   — Resume (proxied)
+POST   /api/mission-control/sessions/:id/kill     — Kill (proxied)
+GET    /api/mission-control/tree                  — Full agent tree (all providers)
+GET    /api/mission-control/audit                 — Operator audit log (paginated)
+```
+
+### Authorization
+
+All Mission Control endpoints require auth + workspace context.
+
+- `operator` role: full access (read + inject + kill + pause)
+- `observer` role: read-only (no inject, no kill, no pause)
+- `admin` role: full access + provider config management
+
+---
+
+## Frontend — Mission Control Page
+
+### Route
+
+`/mission-control` — new top-level page in the web app, linked in sidebar under "Orchestration"
+
+### Layout
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ⚙ MISSION CONTROL              [+ Add Panel] [🔴 KILL ALL]     │
+├──────────────────────────────────────┬──────────────────────────┤
+│                                      │ ACTIVE AGENTS            │
+│  ┌──────────────┬──────────────┐     │ ▼ ms22 [internal] 🟢    │
+│  │ [Panel: ms22]│ [Panel: SAGE]│     │   ├ codex-1 task-api 🟢 │
+│  │  🟢 3 agents │  🟡 1 agent  │     │   ├ codex-2 task-ui  🟢 │
+│  │              │              │     │   └ glm-1   task-db  🟡 │
+│  │ [chat stream]│ [chat stream]│     │ ▼ SAGE [openclaw] 🟢    │
+│  │              │              │     │   └ codex-1 task-prd 🟢 │
+│  │ [input    ▶] │ [input    ▶] │     │                          │
+│  │ [⚡][⏸][💀] │ [⚡][⏸][💀] │     │ [⏸ pause] [💀 kill] per │
+│  └──────────────┴──────────────┘     │ agent                   │
+│                                      │                          │
+│  [+ Add Orchestrator Panel]          │ [📋 Audit Log]          │
+└──────────────────────────────────────┴──────────────────────────┘
+```
+
+### Components
+
+**MissionControlPage** (`/app/mission-control/page.tsx`)
+
+- Fetches active sessions from `/api/mission-control/sessions`
+- Renders N `OrchestratorPanel` in a responsive CSS grid
+- Sidebar: `GlobalAgentRoster`
+- Header: session count, Kill All button (confirm dialog)
+
+**OrchestratorPanel** (`components/mission-control/OrchestratorPanel.tsx`)
+
+- Props: `sessionId`, `provider`, `title`
+- Subscribes to `/api/mission-control/sessions/:id/stream` (SSE)
+- Renders scrollable message list (role-tagged, styled by role)
+- Input box + Send button (barge-in → `POST /inject`)
+- Header: status badge, agent count, elapsed time, ⚡ Barge-In toggle, ⏸ Pause, 💀 Kill
+- Expandable to full-screen (modal overlay)
+- Color-coded border by status (green/yellow/red/gray)
+
+**GlobalAgentRoster** (`components/mission-control/GlobalAgentRoster.tsx`)
+
+- Fetches `/api/mission-control/tree`
+- Renders tree: orch session → indented subagents
+- Per-row: provider badge, status dot, task label, elapsed, Kill button
+- Real-time updates via polling or SSE events
+
+**BargeInInput** (`components/mission-control/BargeInInput.tsx`)
+
+- Elevated textarea that renders inside a panel
+- "Pause before send" checkbox
+- Sends to `POST /inject`, shows confirmation
+
+**AuditLogDrawer** (`components/mission-control/AuditLogDrawer.tsx`)
+
+- Slide-in drawer from right
+- Paginated table: timestamp, user, action, session, content preview
+- Triggered from sidebar "Audit Log" button
+
+**KillAllDialog** (`components/mission-control/KillAllDialog.tsx`)
+
+- Confirmation modal with provider scope selector
+- "Kill all internal agents" / "Kill all (all providers)"
+- Requires typing "KILL ALL" to confirm
+
+---
+
+## Implementation Phases
+
+### Phase 0 — Foundation (Backend Core)
+
+Backend infrastructure required before any UI work.
+
+| Task        | Description                                                                                                                    | Scope        | Est |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------ | --- |
+| MS23-P0-001 | Prisma schema: AgentConversationMessage, AgentSessionTree, AgentProviderConfig, OperatorAuditLog — see mosaic-queue note below | api          | 15K |
+| MS23-P0-002 | Agent message ingestion: wire spawner/lifecycle to write messages to DB                                                        | orchestrator | 20K |
+| MS23-P0-003 | Orchestrator API: `GET /agents/:id/messages` + SSE stream endpoint                                                             | orchestrator | 20K |
+| MS23-P0-004 | Orchestrator API: `POST /agents/:id/inject` + pause/resume                                                                     | orchestrator | 15K |
+| MS23-P0-005 | Subagent tree: `parentAgentId` on spawn registration + `GET /agents/tree`                                                      | orchestrator | 15K |
+| MS23-P0-006 | Unit + integration tests for all P0 orchestrator endpoints                                                                     | orchestrator | 20K |
+
+**Phase 0 gate:** All orchestrator endpoints tested and green. Per-agent message stream verified via curl/SSE client.
+
+> **mosaic-queue Integration Note**
+>
+> `mosaic-queue` (`~/src/mosaic-queue`) is a standalone Valkey-backed task registry (CLI + MCP server) that agents use to claim and complete tasks in a pull model. It is complementary to — not a replacement for — the orchestrator's internal `QueueService` (which is push-based agent dispatch).
+>
+> **Schema impact on MS23-P0-001:**
+>
+> - `AgentSessionTree.taskId` should be `String?` and optionally reference a mosaic-queue task key
+> - Add `AgentSessionTree.taskSource String? @default("internal")` — values: `"internal"` | `"mosaic-queue"` | `"external"`
+> - This allows Mission Control's agent roster to resolve task metadata (title, priority, status) from the correct source
+>
+> **Future integration point:**
+> mosaic-queue Phase 3 ("coordinator integration") will wire the coordinator to claim tasks from mosaic-queue and spawn orchestrator agents against them. When that ships, Mission Control will inherit rich task context (title, lane, priority, retry count) from the queue automatically — no rework needed in MS23's data model if `taskSource` is present from the start.
+>
+> **No blocking dependency:** mosaic-queue Phase 3 is not required for MS23. The `taskSource` field is additive and can be `null` initially.
+
+### Phase 1 — Provider Interface (Plugin Architecture)
+
+| Task        | Description                                                                                                      | Scope  | Est |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- | ------ | --- |
+| MS23-P1-001 | `IAgentProvider` interface + shared types in `packages/shared`                                                   | shared | 10K |
+| MS23-P1-002 | `InternalAgentProvider`: wrap existing orchestrator services behind interface                                    | api    | 20K |
+| MS23-P1-003 | `AgentProviderRegistry`: register/retrieve providers, aggregate listSessions                                     | api    | 15K |
+| MS23-P1-004 | `AgentProviderConfig` CRUD API (`/api/agent-providers`)                                                          | api    | 15K |
+| MS23-P1-005 | Mission Control proxy API (`/api/mission-control/*`): routes to registry, handles SSE proxying, writes audit log | api    | 30K |
+| MS23-P1-006 | Unit tests for registry, proxy service, internal provider                                                        | api    | 20K |
+
+**Phase 1 gate:** Unified `/api/mission-control/sessions` returns sessions from internal provider. Proxy routes correctly to internal provider for kill/pause/inject. Audit log persisted.
+
+### Phase 2 — Mission Control UI
+
+| Task        | Description                                                             | Scope | Est |
+| ----------- | ----------------------------------------------------------------------- | ----- | --- |
+| MS23-P2-001 | `/mission-control` page route + layout shell                            | web   | 10K |
+| MS23-P2-002 | `OrchestratorPanel` component: SSE message stream, chat display         | web   | 25K |
+| MS23-P2-003 | `BargeInInput` component: inject message, pause-before-send             | web   | 15K |
+| MS23-P2-004 | Panel operator controls: pause, resume, graceful kill, hard kill        | web   | 15K |
+| MS23-P2-005 | `GlobalAgentRoster` sidebar: tree view, per-agent kill                  | web   | 20K |
+| MS23-P2-006 | `KillAllDialog`: confirmation modal with scope selector                 | web   | 10K |
+| MS23-P2-007 | `AuditLogDrawer`: paginated audit history                               | web   | 15K |
+| MS23-P2-008 | Panel grid: responsive layout, add/remove panels, expand to full-screen | web   | 20K |
+| MS23-P2-009 | Frontend tests (vitest + Playwright E2E for mission control page)       | web   | 25K |
+
+**Phase 2 gate:** Mission Control page renders with live panels. Barge-in sends and displays. Kill triggers confirmation and removes agent from roster. Audit log shows entries. All tests green.
+
+### Phase 3 — OpenClaw Provider Adapter
+
+| Task        | Description                                                                        | Scope   | Est |
+| ----------- | ---------------------------------------------------------------------------------- | ------- | --- |
+| MS23-P3-001 | `OpenClawProvider`: implement `IAgentProvider` against OpenClaw REST API           | api     | 25K |
+| MS23-P3-002 | OpenClaw session polling / SSE bridge: translate OpenClaw events to `AgentMessage` | api     | 20K |
+| MS23-P3-003 | Provider config UI: register OpenClaw gateway (URL + API token) in Settings        | web     | 15K |
+| MS23-P3-004 | E2E test: OpenClaw provider registered → sessions appear in Mission Control        | api+web | 20K |
+
+**Phase 3 gate:** OpenClaw sessions visible in Mission Control alongside internal agents. Barge-in to OpenClaw session injects message and shows in panel stream.
+
+### Phase 4 — Verification & Release
+
+| Task        | Description                                                                             | Scope | Est |
+| ----------- | --------------------------------------------------------------------------------------- | ----- | --- |
+| MS23-P4-001 | Full QA: all gates (lint, typecheck, unit, E2E)                                         | stack | 10K |
+| MS23-P4-002 | Security review: auth on all new endpoints, audit log integrity, barge-in rate limiting | api   | 10K |
+| MS23-P4-003 | Deploy to production (mosaic.woltje.com), smoke test with live agents                   | stack | 5K  |
+| MS23-P4-004 | Update ROADMAP.md + CHANGELOG.md, tag v0.0.23                                           | stack | 3K  |
+
+---
+
+## Completion Gates (Mandatory)
+
+Per Mosaic E2E delivery framework — a task is NOT done until:
+
+- [ ] Code review (independent review of every changed file)
+- [ ] Security review (auth, input validation, error leakage)
+- [ ] QA / tests green (`pnpm turbo lint typecheck test`)
+- [ ] CI pipeline green after merge
+- [ ] Gitea issue closed
+- [ ] Docs updated for any API or schema changes
+
+---
+
+## Token Budget Estimate
+
+| Phase                        | Tasks  | Estimate  |
+| ---------------------------- | ------ | --------- |
+| Phase 0 — Backend Core       | 6      | ~105K     |
+| Phase 1 — Provider Interface | 6      | ~110K     |
+| Phase 2 — Mission Control UI | 9      | ~155K     |
+| Phase 3 — OpenClaw Adapter   | 4      | ~80K      |
+| Phase 4 — Verification       | 4      | ~28K      |
+| **Total**                    | **29** | **~478K** |
+
+Recommended split: Codex for UI (Phase 2) and routine API work. Sonnet for provider interface design and complex streaming logic.
+
+---
+
+## Security Considerations
+
+- All Mission Control endpoints require authenticated session + workspace membership
+- Barge-in rate-limited: 10 requests/minute per operator per session
+- Kill All requires explicit confirmation (UI + double-confirm pattern)
+- External provider credentials stored encrypted (AES-256-GCM via CryptoService)
+- Audit log is append-only; no delete endpoint
+- SSE streams authenticated via session cookie (no unauthenticated streams)
+- Operator actions tagged with userId for full traceability
+- `observer` role enforced at middleware level — cannot be bypassed by frontend
+
+---
+
+## Open Questions
+
+1. **Panel persistence:** Should the grid layout (which sessions are pinned as panels) be stored in DB per user or in localStorage? Recommend DB for cross-device consistency.
+2. **Message retention:** How long to keep `AgentConversationMessage` records? Suggest 30-day default with configurable workspace policy.
+3. **OpenClaw barge-in protocol:** Does OpenClaw's `sessions_send` API support injection mid-run, or does it queue behind the current turn? Needs verification against OpenClaw API before MS23-P3-001.
+4. **Subagent reporting:** Internal agents currently don't self-report a `parentAgentId` at spawn time. The orchestrator spawner needs to accept this field. Straightforward add to `SpawnAgentDto`.
+5. **SSE vs WebSocket for message streaming:** Current orchestrator uses SSE (one-way push). For barge-in confirmation/ack, SSE is sufficient (inject is a separate REST call). No need to upgrade to bidirectional WebSocket for Phase 0-2.
+
+6. **mosaic-queue Phase 3 timing:** mosaic-queue's coordinator integration phase is not yet scheduled. If it ships during MS23 development, the `taskSource` field in `AgentSessionTree` is the integration point — no schema migration required. The Mission Control roster can conditionally render task details from mosaic-queue when `taskSource === "mosaic-queue"` and the queue MCP/API is reachable.
+
+---
+
+## Success Criteria
+
+1. Operator can open Mission Control and see all running orchestrator sessions as live panels
+2. Each panel shows the agent's actual conversation messages in real time
+3. Operator can type into any panel and inject a message; it appears in the stream tagged `[OPERATOR]`
+4. Operator can pause, resume, gracefully terminate, or hard-kill any agent from the panel or roster
+5. Global Agent Roster shows the full parent → subagent tree across all providers
+6. Kill All button with confirmation terminates all active agents
+7. All operator actions appear in the Audit Log with full attribution
+8. OpenClaw sessions registered as an external provider appear in Mission Control alongside internal agents
+9. `observer` role users can see everything but cannot inject, pause, or kill
+10. All CI gates green, deployed to production

docs/TASKS.md

@@ -94,15 +94,92 @@ Design doc: `docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md`
 
 PRD: `docs/PRD-MS22-P2-AGENT-FLEET.md`
 
-| Task ID     | Status      | Phase    | Description                                  | Issue    | Scope | Branch                      | Depends On    | Blocks        | Assigned Worker | Started    | Completed  | Est Tokens | Act Tokens | Notes          |
+| Task ID     | Status | Phase    | Description                                  | Issue    | Scope | Branch                      | Depends On    | Blocks        | Assigned Worker | Started    | Completed  | Est Tokens | Act Tokens | Notes           |
-| ----------- | ----------- | -------- | -------------------------------------------- | -------- | ----- | --------------------------- | ------------- | ------------- | --------------- | ---------- | ---------- | ---------- | ---------- | -------------- |
+| ----------- | ------ | -------- | -------------------------------------------- | -------- | ----- | --------------------------- | ------------- | ------------- | --------------- | ---------- | ---------- | ---------- | ---------- | --------------- |
-| MS22-P2-001 | done        | p2-fleet | Prisma schema: AgentTemplate, UserAgent      | TASKS:P2 | api   | feat/ms22-p2-agent-schema   | MS22-P1a      | P2-002,P2-003 | orchestrator    | 2026-03-04 | 2026-03-04 | 10K        | 3K         | PR #675 merged |
+| MS22-P2-001 | done   | p2-fleet | Prisma schema: AgentTemplate, UserAgent      | TASKS:P2 | api   | feat/ms22-p2-agent-schema   | MS22-P1a      | P2-002,P2-003 | orchestrator    | 2026-03-04 | 2026-03-04 | 10K        | 3K         | PR #675 merged  |
-| MS22-P2-002 | done        | p2-fleet | Seed default agents (jarvis, builder, medic) | TASKS:P2 | api   | feat/ms22-p2-agent-seed     | P2-001        | P2-004        | orchestrator    | 2026-03-04 | 2026-03-04 | 5K         | 2K         | PR #677 merged |
+| MS22-P2-002 | done   | p2-fleet | Seed default agents (jarvis, builder, medic) | TASKS:P2 | api   | feat/ms22-p2-agent-seed     | P2-001        | P2-004        | orchestrator    | 2026-03-04 | 2026-03-04 | 5K         | 2K         | PR #677 merged  |
-| MS22-P2-003 | done        | p2-fleet | Agent template CRUD endpoints (admin)        | TASKS:P2 | api   | feat/ms22-p2-agent-crud     | P2-001        | P2-005        | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 5K         | PR #678 merged |
+| MS22-P2-003 | done   | p2-fleet | Agent template CRUD endpoints (admin)        | TASKS:P2 | api   | feat/ms22-p2-agent-crud     | P2-001        | P2-005        | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 5K         | PR #678 merged  |
-| MS22-P2-004 | done        | p2-fleet | User agent CRUD endpoints                    | TASKS:P2 | api   | feat/ms22-p2-user-agents    | P2-002,P2-003 | P2-006        | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 8K         | PR #682 merged |
+| MS22-P2-004 | done   | p2-fleet | User agent CRUD endpoints                    | TASKS:P2 | api   | feat/ms22-p2-user-agents    | P2-002,P2-003 | P2-006        | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 8K         | PR #682 merged  |
-| MS22-P2-005 | in-progress | p2-fleet | Agent status endpoints                       | TASKS:P2 | api   | feat/ms22-p2-agent-status   | P2-003        | P2-008        | orchestrator    | 2026-03-04 | —          | 10K        | —          |                |
+| MS22-P2-005 | done   | p2-fleet | Agent status endpoints                       | TASKS:P2 | api   | feat/ms22-p2-agent-routing  | P2-003        | P2-008        | orchestrator    | 2026-03-04 | 2026-03-04 | 10K        | 5K         | PR #684 merged  |
-| MS22-P2-006 | not-started | p2-fleet | Agent chat routing (select agent by name)    | TASKS:P2 | api   | feat/ms22-p2-agent-routing  | P2-004        | P2-007        | —               | —          | —          | 15K        | —          |                |
+| MS22-P2-006 | done   | p2-fleet | Agent chat routing (select agent by name)    | TASKS:P2 | api   | feat/ms22-p2-agent-routing  | P2-004        | P2-007        | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 5K         | PR #684 merged  |
-| MS22-P2-007 | not-started | p2-fleet | Discord channel → agent routing              | TASKS:P2 | api   | feat/ms22-p2-discord-router | P2-006        | P2-009        | —               | —          | —          | 15K        | —          |                |
+| MS22-P2-007 | done   | p2-fleet | Discord channel → agent routing              | TASKS:P2 | api   | feat/ms22-p2-discord-router | P2-006        | P2-010        | orchestrator    | 2026-03-05 | 2026-03-05 | 15K        | 8K         | PR #688         |
-| MS22-P2-008 | not-started | p2-fleet | Agent list/selector UI in WebUI              | TASKS:P2 | web   | feat/ms22-p2-agent-ui       | P2-005        | —             | —               | —          | —          | 15K        | —          |                |
+| MS22-P2-008 | done   | p2-fleet | Agent list/selector UI in WebUI              | TASKS:P2 | web   | feat/ms22-p2-agent-ui       | P2-005        | —             | orchestrator    | 2026-03-04 | 2026-03-04 | 15K        | 8K         | PR #685 merged  |
-| MS22-P2-009 | not-started | p2-fleet | Unit tests for agent services                | TASKS:P2 | api   | test/ms22-p2-agent-tests    | P2-007        | P2-010        | —               | —          | —          | 15K        | —          |                |
+| MS22-P2-009 | done   | p2-fleet | Unit tests for agent services                | TASKS:P2 | api   | test/ms22-p2-agent-tests    | P2-006        | P2-010        | orchestrator    | 2026-03-04 | 2026-03-05 | 15K        | 8K         | PR #687 merged  |
-| MS22-P2-010 | not-started | p2-fleet | E2E verification: Discord → agent → response | TASKS:P2 | stack | —                           | P2-009        | —             | —               | —          | —          | 10K        | —          |                |
+| MS22-P2-010 | done   | p2-fleet | E2E verification: Discord → agent → response | TASKS:P2 | stack | —                           | P2-009        | —             | orchestrator    | 2026-03-05 | 2026-03-05 | 10K        | 5K         | All gates green |
+
+---
+
+## MS23 — Mission Control Dashboard & Agent Provider Interface
+
+PRD: `docs/PRD-MS23-mission-control.md`
+Milestone: `0.0.23`
+Target version: `v0.0.23`
+
+> Single-writer: orchestrator (Jarvis/OpenClaw) only. Workers read but never modify.
+
+### Phase 0 — Backend Core (Foundation)
+
+| id          | status      | milestone     | description                                                                                      | issue | repo         | branch                 | depends_on                                      | blocks                                                      | agent | started_at | completed_at | estimate | used | notes                                         |
+| ----------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------ | ----- | ------------ | ---------------------- | ----------------------------------------------- | ----------------------------------------------------------- | ----- | ---------- | ------------ | -------- | ---- | --------------------------------------------- |
+| MS23-P0-001 | done        | p0-foundation | Prisma schema: AgentConversationMessage, AgentSessionTree, AgentProviderConfig, OperatorAuditLog | #693  | api          | feat/ms23-p0-schema    | —                                               | MS23-P0-002,MS23-P0-003,MS23-P0-004,MS23-P0-005,MS23-P1-001 | codex | 2026-03-06 | 2026-03-06   | 15K      | —    | taskSource field per mosaic-queue note in PRD |
+| MS23-P0-002 | done        | p0-foundation | Agent message ingestion: wire spawner/lifecycle to write messages to DB                          | #693  | orchestrator | feat/ms23-p0-ingestion | MS23-P0-001                                     | MS23-P0-006                                                 | codex | 2026-03-06 | 2026-03-07      | 20K      | —    |                                               |
+| MS23-P0-003 | done        | p0-foundation | Orchestrator API: GET /agents/:id/messages + SSE stream endpoint                                 | #693  | orchestrator | feat/ms23-p0-stream    | MS23-P0-001                                     | MS23-P0-006                                                 | codex | 2026-03-06 | 2026-03-07      | 20K      | —    |                                               |
+| MS23-P0-004 | done        | p0-foundation | Orchestrator API: POST /agents/:id/inject + pause/resume endpoints                               | #693  | orchestrator | feat/ms23-p0-controls  | MS23-P0-001                                     | MS23-P0-006                                                 | codex | 2026-03-07 | 2026-03-07 | 15K      | —    |                                               |
+| MS23-P0-005 | done        | p0-foundation | Subagent tree: parentAgentId on spawn registration + GET /agents/tree                            | #693  | orchestrator | feat/ms23-p0-tree      | MS23-P0-001                                     | MS23-P0-006                                                 | —     | —          | —            | 15K      | —    |                                               |
+| MS23-P0-006 | done        | p0-foundation | Unit + integration tests for all P0 orchestrator endpoints                                       | #693  | orchestrator | test/ms23-p0           | MS23-P0-002,MS23-P0-003,MS23-P0-004,MS23-P0-005 | MS23-P1-001                                                 | codex | 2026-03-07 | 2026-03-07 | 20K      | —    | Phase 0 gate: SSE stream verified via curl    |
+
+### Phase 1 — Provider Interface (Plugin Architecture)
+
+| id          | status      | milestone   | description                                                                         | issue | repo   | branch                         | depends_on                          | blocks                  | agent | started_at | completed_at | estimate | used | notes                                                              |
+| ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------- | ----- | ------ | ------------------------------ | ----------------------------------- | ----------------------- | ----- | ---------- | ------------ | -------- | ---- | ------------------------------------------------------------------ |
+| MS23-P1-001 | not-started | p1-provider | IAgentProvider interface + AgentSession/AgentMessage types in packages/shared       | #694  | shared | feat/ms23-p1-interface         | MS23-P0-001,MS23-P0-006             | MS23-P1-002,MS23-P1-003 | —     | —          | —            | 10K      | —    |                                                                    |
+| MS23-P1-002 | not-started | p1-provider | InternalAgentProvider: wrap existing orchestrator services behind IAgentProvider    | #694  | api    | feat/ms23-p1-internal-provider | MS23-P1-001                         | MS23-P1-003,MS23-P1-006 | —     | —          | —            | 20K      | —    |                                                                    |
+| MS23-P1-003 | not-started | p1-provider | AgentProviderRegistry: register/retrieve providers, aggregate listSessions          | #694  | api    | feat/ms23-p1-registry          | MS23-P1-001,MS23-P1-002             | MS23-P1-004,MS23-P1-005 | —     | —          | —            | 15K      | —    |                                                                    |
+| MS23-P1-004 | not-started | p1-provider | AgentProviderConfig CRUD API (/api/agent-providers)                                 | #694  | api    | feat/ms23-p1-provider-api      | MS23-P1-003                         | MS23-P1-006             | —     | —          | —            | 15K      | —    |                                                                    |
+| MS23-P1-005 | not-started | p1-provider | Mission Control proxy API (/api/mission-control/\*): SSE proxying, audit log writes | #694  | api    | feat/ms23-p1-proxy             | MS23-P1-003                         | MS23-P1-006,MS23-P2-001 | —     | —          | —            | 30K      | —    | Aggregates all providers; most complex P1 task                     |
+| MS23-P1-006 | not-started | p1-provider | Unit tests: registry, proxy service, internal provider                              | #694  | api    | test/ms23-p1                   | MS23-P1-002,MS23-P1-004,MS23-P1-005 | MS23-P2-001             | —     | —          | —            | 20K      | —    | Phase 1 gate: unified /sessions returns internal provider sessions |
+
+### Phase 2 — Mission Control UI
+
+| id          | status      | milestone | description                                                                         | issue | repo | branch                | depends_on                                                              | blocks                  | agent | started_at | completed_at | estimate | used | notes                                 |
+| ----------- | ----------- | --------- | ----------------------------------------------------------------------------------- | ----- | ---- | --------------------- | ----------------------------------------------------------------------- | ----------------------- | ----- | ---------- | ------------ | -------- | ---- | ------------------------------------- |
+| MS23-P2-001 | not-started | p2-ui     | /mission-control page route + layout shell (sidebar + panel grid)                   | #695  | web  | feat/ms23-p2-page     | MS23-P1-005,MS23-P1-006                                                 | MS23-P2-002,MS23-P2-005 | —     | —          | —            | 10K      | —    |                                       |
+| MS23-P2-002 | not-started | p2-ui     | OrchestratorPanel component: SSE message stream, chat display, role-tagged messages | #695  | web  | feat/ms23-p2-panel    | MS23-P2-001                                                             | MS23-P2-003,MS23-P2-004 | —     | —          | —            | 25K      | —    |                                       |
+| MS23-P2-003 | not-started | p2-ui     | BargeInInput component: inject message, pause-before-send checkbox                  | #695  | web  | feat/ms23-p2-barge    | MS23-P2-002                                                             | MS23-P2-009             | —     | —          | —            | 15K      | —    |                                       |
+| MS23-P2-004 | not-started | p2-ui     | Panel operator controls: pause, resume, graceful kill, hard kill buttons            | #695  | web  | feat/ms23-p2-controls | MS23-P2-002                                                             | MS23-P2-009             | —     | —          | —            | 15K      | —    |                                       |
+| MS23-P2-005 | not-started | p2-ui     | GlobalAgentRoster sidebar: tree view, per-agent kill buttons                        | #695  | web  | feat/ms23-p2-roster   | MS23-P2-001                                                             | MS23-P2-006,MS23-P2-009 | —     | —          | —            | 20K      | —    |                                       |
+| MS23-P2-006 | not-started | p2-ui     | KillAllDialog: confirmation modal with scope selector (internal / all providers)    | #695  | web  | feat/ms23-p2-killall  | MS23-P2-005                                                             | MS23-P2-009             | —     | —          | —            | 10K      | —    | Requires typing "KILL ALL" to confirm |
+| MS23-P2-007 | not-started | p2-ui     | AuditLogDrawer: paginated audit history slide-in drawer                             | #695  | web  | feat/ms23-p2-audit    | MS23-P2-001                                                             | MS23-P2-009             | —     | —          | —            | 15K      | —    |                                       |
+| MS23-P2-008 | not-started | p2-ui     | Panel grid: responsive layout, add/remove panels, full-screen expand                | #695  | web  | feat/ms23-p2-grid     | MS23-P2-002                                                             | MS23-P2-009             | —     | —          | —            | 20K      | —    |                                       |
+| MS23-P2-009 | not-started | p2-ui     | Frontend tests: vitest unit + Playwright E2E for mission control page               | #695  | web  | test/ms23-p2          | MS23-P2-003,MS23-P2-004,MS23-P2-005,MS23-P2-006,MS23-P2-007,MS23-P2-008 | MS23-P3-001             | —     | —          | —            | 25K      | —    | Phase 2 gate                          |
+
+### Phase 3 — OpenClaw Provider Adapter
+
+| id          | status      | milestone   | description                                                                      | issue | repo    | branch                         | depends_on  | blocks      | agent | started_at | completed_at | estimate | used | notes                                               |
+| ----------- | ----------- | ----------- | -------------------------------------------------------------------------------- | ----- | ------- | ------------------------------ | ----------- | ----------- | ----- | ---------- | ------------ | -------- | ---- | --------------------------------------------------- |
+| MS23-P3-001 | not-started | p3-openclaw | OpenClawProvider: implement IAgentProvider against OpenClaw REST API             | #696  | api     | feat/ms23-p3-openclaw-provider | MS23-P2-009 | MS23-P3-002 | —     | —          | —            | 25K      | —    | Verify barge-in protocol (see PRD open question #3) |
+| MS23-P3-002 | not-started | p3-openclaw | OpenClaw session polling / SSE bridge: translate OpenClaw events to AgentMessage | #696  | api     | feat/ms23-p3-openclaw-bridge   | MS23-P3-001 | MS23-P3-003 | —     | —          | —            | 20K      | —    |                                                     |
+| MS23-P3-003 | not-started | p3-openclaw | Provider config UI: register OpenClaw gateway (URL + API token) in Settings      | #696  | web     | feat/ms23-p3-config-ui         | MS23-P3-002 | MS23-P3-004 | —     | —          | —            | 15K      | —    |                                                     |
+| MS23-P3-004 | not-started | p3-openclaw | E2E test: OpenClaw provider registered → sessions appear in Mission Control      | #696  | api+web | test/ms23-p3                   | MS23-P3-003 | MS23-P4-001 | —     | —          | —            | 20K      | —    | Phase 3 gate                                        |
+
+### Phase 4 — Verification & Release
+
+| id          | status      | milestone  | description                                                                             | issue | repo  | branch | depends_on  | blocks      | agent | started_at | completed_at | estimate | used | notes |
+| ----------- | ----------- | ---------- | --------------------------------------------------------------------------------------- | ----- | ----- | ------ | ----------- | ----------- | ----- | ---------- | ------------ | -------- | ---- | ----- |
+| MS23-P4-001 | not-started | p4-release | Full QA: pnpm turbo lint typecheck test — all green                                     | #697  | stack | —      | MS23-P3-004 | MS23-P4-002 | —     | —          | —            | 10K      | —    |       |
+| MS23-P4-002 | not-started | p4-release | Security review: auth on all new endpoints, audit log integrity, barge-in rate limiting | #697  | api   | —      | MS23-P4-001 | MS23-P4-003 | —     | —          | —            | 10K      | —    |       |
+| MS23-P4-003 | not-started | p4-release | Deploy to production (mosaic.woltje.com), smoke test with live agents                   | #697  | stack | —      | MS23-P4-002 | MS23-P4-004 | —     | —          | —            | 5K       | —    |       |
+| MS23-P4-004 | not-started | p4-release | Update ROADMAP.md + CHANGELOG.md, tag v0.0.23                                           | #697  | stack | —      | MS23-P4-003 | —           | —     | —          | —            | 3K       | —    |       |
+
+### MS23 Budget Summary
+
+| Phase                        | Tasks  | Estimate  |
+| ---------------------------- | ------ | --------- |
+| Phase 0 — Backend Core       | 6      | ~105K     |
+| Phase 1 — Provider Interface | 6      | ~110K     |
+| Phase 2 — Mission Control UI | 9      | ~155K     |
+| Phase 3 — OpenClaw Adapter   | 4      | ~80K      |
+| Phase 4 — Verification       | 4      | ~28K      |
+| **Total**                    | **29** | **~478K** |
+
+Recommended dispatch: Codex for Phase 2 UI + routine API tasks; Sonnet for complex streaming logic (P0-003, P1-005, P3-002).

docs/scratchpads/ms22-p2-named-agent-fleet-20260304.md

@@ -13,10 +13,25 @@
 
 ## Session Log
 
-| Session | Date       | Milestone | Tasks Done             | Outcome                                                                        |
+| Session | Date       | Milestone | Tasks Done             | Outcome                                                                                       |
-| ------- | ---------- | --------- | ---------------------- | ------------------------------------------------------------------------------ |
+| ------- | ---------- | --------- | ---------------------- | --------------------------------------------------------------------------------------------- |
-| 2       | 2026-03-04 | M1+M2+M3  | P2-004 done            | Fixed CI security audit, merged PRs #681, #678, #682. Milestones 1-3 complete. |
+| 5       | 2026-03-05 | M6        | P2-010 done            | E2E verification: 3547 tests pass, all CI gates green. Mission complete.                      |
-| 1       | 2026-03-04 | M1+M2     | P2-001, P2-002, P2-003 | Schema, seed, and Admin CRUD complete                                          |
+| 4       | 2026-03-05 | M5+M6     | P2-007 done            | Discord channel→agent routing. Fixed lint/type errors. PR #688 merged. 9/10 tasks done.       |
+| 3       | 2026-03-05 | M4+M5     | P2-008 done            | Fixed corrupted AgentSelector.tsx, integrated into Chat.tsx. PR #685 merged. 8/10 tasks done. |
+| 2       | 2026-03-04 | M1+M2+M3  | P2-004 done            | Fixed CI security audit, merged PRs #681, #678, #682. Milestones 1-3 complete.                |
+| 1       | 2026-03-04 | M1+M2     | P2-001, P2-002, P2-003 | Schema, seed, and Admin CRUD complete                                                         |
+
+## Mission Complete
+
+All 10 tasks completed. Success criteria verified:
+
+1. ✅ AgentTemplate and UserAgent tables in Prisma schema
+2. ✅ Admin CRUD at /admin/agent-templates
+3. ✅ User CRUD at /api/agents
+4. ✅ Chat proxy routes by agent name
+5. ✅ Discord channel routing via DISCORD_AGENT_CHANNELS
+6. ✅ WebUI AgentSelector component
+7. ✅ 3547 tests passing, CI green
 
 ## Open Questions
 

packages/shared/src/types/agent-provider.types.ts

@@ -0,0 +1,78 @@
+// Agent message roles
+export type AgentMessageRole = "user" | "assistant" | "system" | "tool";
+
+// A single message in an agent conversation
+export interface AgentMessage {
+  id: string;
+  sessionId: string;
+  role: AgentMessageRole;
+  content: string;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+
+// Session lifecycle status
+export type AgentSessionStatus = "active" | "paused" | "completed" | "failed" | "idle";
+
+// An agent session (conversation thread)
+export interface AgentSession {
+  id: string;
+  providerId: string; // which provider owns this session
+  providerType: string; // "internal" | "openclaw" | etc.
+  label?: string;
+  status: AgentSessionStatus;
+  parentSessionId?: string; // for subagent trees
+  createdAt: Date;
+  updatedAt: Date;
+  metadata?: Record<string, unknown>;
+}
+
+// Result of listing sessions
+export interface AgentSessionList {
+  sessions: AgentSession[];
+  total: number;
+  cursor?: string;
+}
+
+// Result of injecting a message
+export interface InjectResult {
+  accepted: boolean;
+  messageId?: string;
+}
+
+// The IAgentProvider interface — every provider (internal, OpenClaw, future) implements this
+export interface IAgentProvider {
+  readonly providerId: string;
+  readonly providerType: string;
+  readonly displayName: string;
+
+  // Session management
+  listSessions(cursor?: string, limit?: number): Promise<AgentSessionList>;
+  getSession(sessionId: string): Promise<AgentSession | null>;
+  getMessages(sessionId: string, limit?: number, before?: string): Promise<AgentMessage[]>;
+
+  // Control operations
+  injectMessage(sessionId: string, content: string): Promise<InjectResult>;
+  pauseSession(sessionId: string): Promise<void>;
+  resumeSession(sessionId: string): Promise<void>;
+  killSession(sessionId: string, force?: boolean): Promise<void>;
+
+  // SSE streaming — returns an AsyncIterable of AgentMessage events
+  streamMessages(sessionId: string): AsyncIterable<AgentMessage>;
+
+  // Health
+  isAvailable(): Promise<boolean>;
+}
+
+// Provider configuration stored in DB (AgentProviderConfig model from P0 schema)
+export interface AgentProviderConfig {
+  id: string;
+  providerId: string;
+  providerType: string;
+  displayName: string;
+  baseUrl?: string;
+  apiToken?: string;
+  enabled: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}

packages/shared/src/types/index.ts

@@ -134,3 +134,6 @@ export * from "./widget.types";
 
 // Export WebSocket types
 export * from "./websocket.types";
+
+// Export agent provider types
+export * from "./agent-provider.types";

pnpm-lock.yaml

@@ -337,6 +337,9 @@ importers:
       '@nestjs/throttler':
         specifier: ^6.5.0
         version: 6.5.0(@nestjs/common@11.1.12(class-transformer@0.5.1)(class-validator@0.14.3)(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@11.1.12)(reflect-metadata@0.2.2)
+      '@prisma/client':
+        specifier: ^6.19.2
+        version: 6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3)
       bullmq:
         specifier: ^5.67.2
         version: 5.67.2
@@ -386,6 +389,9 @@ importers:
       '@vitest/coverage-v8':
         specifier: ^4.0.18
         version: 4.0.18(vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@22.19.7)(jiti@2.6.1)(jsdom@26.1.0)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      prisma:
+        specifier: ^6.19.2
+        version: 6.19.2(magicast@0.3.5)(typescript@5.9.3)
       ts-node:
         specifier: ^10.9.2
         version: 10.9.2(@swc/core@1.15.11)(@types/node@22.19.7)(typescript@5.9.3)
@@ -8005,7 +8011,7 @@ snapshots:
       chalk: 5.6.2
       commander: 12.1.0
       dotenv: 17.2.4
-      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
+      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
       open: 10.2.0
       pg: 8.17.2
       prettier: 3.8.1
@@ -11345,7 +11351,7 @@ snapshots:
     optionalDependencies:
       '@prisma/client': 5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
       better-sqlite3: 12.6.2
-      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
+      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
       next: 16.1.6(@babel/core@7.28.6)(@opentelemetry/api@1.9.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       pg: 8.17.2
       prisma: 6.19.2(magicast@0.3.5)(typescript@5.9.3)
@@ -11370,7 +11376,7 @@ snapshots:
     optionalDependencies:
       '@prisma/client': 6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3)
       better-sqlite3: 12.6.2
-      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
+      drizzle-orm: 0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
       next: 16.1.6(@babel/core@7.28.6)(@opentelemetry/api@1.9.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       pg: 8.17.2
       prisma: 6.19.2(magicast@0.3.5)(typescript@5.9.3)
@@ -12194,17 +12200,6 @@ snapshots:
 
   dotenv@17.2.4: {}
 
-  drizzle-orm@0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)):
-    optionalDependencies:
-      '@opentelemetry/api': 1.9.0
-      '@prisma/client': 5.22.0(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))
-      '@types/pg': 8.16.0
-      better-sqlite3: 12.6.2
-      kysely: 0.28.10
-      pg: 8.17.2
-      postgres: 3.4.8
-      prisma: 6.19.2(magicast@0.3.5)(typescript@5.9.3)
-
   drizzle-orm@0.41.0(@opentelemetry/api@1.9.0)(@prisma/client@6.19.2(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.16.0)(better-sqlite3@12.6.2)(kysely@0.28.10)(pg@8.17.2)(postgres@3.4.8)(prisma@6.19.2(magicast@0.3.5)(typescript@5.9.3)):
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
@@ -12215,7 +12210,6 @@ snapshots:
       pg: 8.17.2
       postgres: 3.4.8
       prisma: 6.19.2(magicast@0.3.5)(typescript@5.9.3)
-    optional: true
 
   dunder-proto@1.0.1:
     dependencies: