feat(web): MS23-P3-003 OpenClaw provider config UI

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

.mosaic/orchestrator/mission.json

@@ -1,56 +1,56 @@
 {
   "schema_version": 1,
-  "mission_id": "ms21-multi-tenant-rbac-data-migration-20260228",
-  "name": "MS21 Multi-Tenant RBAC Data Migration",
-  "description": "Build multi-tenant user/workspace/team management, break-glass auth, RBAC UI enforcement, and migrate jarvis-brain data into Mosaic Stack",
+  "mission_id": "ms22-p2-named-agent-fleet-20260304",
+  "name": "MS22-P2 Named Agent Fleet",
+  "description": "",
   "project_path": "/home/jwoltje/src/mosaic-stack",
-  "created_at": "2026-02-28T17:10:22Z",
+  "created_at": "2026-03-05T01:53:28Z",
   "status": "active",
-  "task_prefix": "MS21",
-  "quality_gates": "pnpm lint && pnpm build && pnpm test",
-  "milestone_version": "0.0.21",
+  "task_prefix": "",
+  "quality_gates": "",
+  "milestone_version": "0.0.1",
   "milestones": [
     {
       "id": "phase-1",
-      "name": "Schema and Admin API",
+      "name": "Schema+Seed",
       "status": "pending",
-      "branch": "schema-and-admin-api",
+      "branch": "schema-seed",
       "issue_ref": "",
       "started_at": "",
       "completed_at": ""
     },
     {
       "id": "phase-2",
-      "name": "Break-Glass Authentication",
+      "name": "Admin CRUD",
       "status": "pending",
-      "branch": "break-glass-authentication",
+      "branch": "admin-crud",
       "issue_ref": "",
       "started_at": "",
       "completed_at": ""
     },
     {
       "id": "phase-3",
-      "name": "Data Migration",
+      "name": "User CRUD",
       "status": "pending",
-      "branch": "data-migration",
+      "branch": "user-crud",
       "issue_ref": "",
       "started_at": "",
       "completed_at": ""
     },
     {
       "id": "phase-4",
-      "name": "Admin UI",
+      "name": "Agent Routing",
       "status": "pending",
-      "branch": "admin-ui",
+      "branch": "agent-routing",
       "issue_ref": "",
       "started_at": "",
       "completed_at": ""
     },
     {
       "id": "phase-5",
-      "name": "RBAC UI Enforcement",
+      "name": "Discord+UI",
       "status": "pending",
-      "branch": "rbac-ui-enforcement",
+      "branch": "discord-ui",
       "issue_ref": "",
       "started_at": "",
       "completed_at": ""
@@ -65,26 +65,5 @@
       "completed_at": ""
     }
   ],
-  "sessions": [
-    {
-      "session_id": "sess-001",
-      "runtime": "unknown",
-      "started_at": "2026-02-28T17:48:51Z",
-      "ended_at": "",
-      "ended_reason": "",
-      "milestone_at_end": "",
-      "tasks_completed": [],
-      "last_task_id": ""
-    },
-    {
-      "session_id": "sess-002",
-      "runtime": "unknown",
-      "started_at": "2026-02-28T20:30:13Z",
-      "ended_at": "",
-      "ended_reason": "",
-      "milestone_at_end": "",
-      "tasks_completed": [],
-      "last_task_id": ""
-    }
-  ]
+  "sessions": []
 }

.mosaic/orchestrator/session.lock

@@ -1,8 +0,0 @@
-{
-  "session_id": "sess-002",
-  "runtime": "unknown",
-  "pid": 3178395,
-  "started_at": "2026-02-28T20:30:13Z",
-  "project_path": "/tmp/ms21-ui-001",
-  "milestone_id": ""
-}

.npmrc

@@ -1 +1,3 @@
 @mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaic/npm/
+supportedArchitectures[libc][]=glibc
+supportedArchitectures[cpu][]=x64

.woodpecker/ci.yml

@@ -29,9 +29,10 @@ when:
         - ".trivyignore"
 
 variables:
-  - &node_image "node:24-alpine"
+  - &node_image "node:24-slim"
   - &install_deps |
     corepack enable
+    apt-get update && apt-get install -y --no-install-recommends python3 make g++
     pnpm config set store-dir /root/.local/share/pnpm/store
     pnpm install --frozen-lockfile
   - &use_deps |
@@ -169,7 +170,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:latest"
         fi
-        /kaniko/executor --context . --dockerfile apps/api/Dockerfile --snapshot-mode=redo $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/api/Dockerfile --snapshot-mode=redo --cache=true --cache-repo git.mosaicstack.dev/mosaic/stack-api/cache $DESTINATIONS
     when:
       - branch: [main]
         event: [push, manual, tag]
@@ -194,7 +195,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:latest"
         fi
-        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile --snapshot-mode=redo $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile --snapshot-mode=redo --cache=true --cache-repo git.mosaicstack.dev/mosaic/stack-orchestrator/cache $DESTINATIONS
     when:
       - branch: [main]
         event: [push, manual, tag]
@@ -219,7 +220,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:latest"
         fi
-        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --snapshot-mode=redo --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --snapshot-mode=redo --cache=true --cache-repo git.mosaicstack.dev/mosaic/stack-web/cache --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
     when:
       - branch: [main]
         event: [push, manual, tag]
@@ -336,3 +337,47 @@ steps:
       - security-trivy-api
       - security-trivy-orchestrator
       - security-trivy-web
+
+  # ─── Deploy to Docker Swarm via Portainer API (main only) ─────────────────────
+
+  deploy-swarm:
+    image: alpine:3
+    failure: ignore
+    environment:
+      PORTAINER_URL:
+        from_secret: portainer_url
+      PORTAINER_API_KEY:
+        from_secret: portainer_api_key
+      PORTAINER_STACK_ID: "121"
+    commands:
+      - apk add --no-cache curl
+      - |
+        set -e
+        echo "🚀 Deploying to Docker Swarm via Portainer API..."
+
+        # Use Portainer API to update the stack (forces pull of new images)
+        RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+          -H "X-API-Key: $PORTAINER_API_KEY" \
+          -H "Content-Type: application/json" \
+          "$PORTAINER_URL/api/stacks/$PORTAINER_STACK_ID/git/redeploy")
+
+        HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+        BODY=$(echo "$RESPONSE" | head -n -1)
+
+        if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "202" ]; then
+          echo "✅ Stack update triggered successfully"
+        else
+          echo "❌ Stack update failed (HTTP $HTTP_CODE)"
+          echo "$BODY"
+          exit 1
+        fi
+
+        # Wait for services to converge
+        echo "⏳ Waiting for services to converge..."
+        sleep 30
+        echo "✅ Deploy complete"
+    when:
+      - branch: [main]
+        event: [push, manual, tag]
+    depends_on:
+      - link-packages

apps/api/Dockerfile

@@ -30,6 +30,9 @@ COPY packages/ui/package.json ./packages/ui/
 COPY packages/config/package.json ./packages/config/
 COPY apps/api/package.json ./apps/api/
 
+# Copy npm configuration for native binary architecture hints
+COPY .npmrc ./
+
 # Install dependencies (no cache mount — Kaniko builds are ephemeral in CI)
 # Then explicitly rebuild node-pty from source since pnpm may skip postinstall
 # scripts or fail to find prebuilt binaries for this Node.js version

apps/api/prisma/migrations/20260303000001_ms21_user_auth_fields/migration.sql

@@ -0,0 +1,13 @@
+-- MS21: Add admin, local auth, and invitation fields to users table
+-- These columns were added to schema.prisma but never captured in a migration.
+
+ALTER TABLE "users"
+  ADD COLUMN IF NOT EXISTS "deactivated_at" TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS "is_local_auth" BOOLEAN NOT NULL DEFAULT false,
+  ADD COLUMN IF NOT EXISTS "password_hash" TEXT,
+  ADD COLUMN IF NOT EXISTS "invited_by" UUID,
+  ADD COLUMN IF NOT EXISTS "invitation_token" TEXT,
+  ADD COLUMN IF NOT EXISTS "invited_at" TIMESTAMPTZ;
+
+-- CreateIndex
+CREATE UNIQUE INDEX IF NOT EXISTS "users_invitation_token_key" ON "users"("invitation_token");

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

@@ -1703,3 +1703,102 @@ model UserAgentConfig {
   createdAt      DateTime @default(now())
   updatedAt      DateTime @updatedAt
 }
+
+model AgentTemplate {
+  id              String   @id @default(cuid())
+  name            String   @unique // "jarvis", "builder", "medic"
+  displayName     String // "Jarvis", "Builder", "Medic"
+  role            String // "orchestrator" | "coding" | "monitoring"
+  personality     String // SOUL.md content (markdown)
+  primaryModel    String // "opus", "codex", "haiku"
+  fallbackModels  Json     @default("[]") // ["sonnet", "haiku"]
+  toolPermissions Json     @default("[]") // ["exec", "read", "write", ...]
+  discordChannel  String? // "jarvis", "builder", "medic-alerts"
+  isActive        Boolean  @default(true)
+  isDefault       Boolean  @default(false) // Include in new user provisioning
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+}
+
+model UserAgent {
+  id              String   @id @default(cuid())
+  userId          String
+  templateId      String? // null = custom agent
+  name            String // "jarvis", "builder", "medic" or custom
+  displayName     String
+  role            String
+  personality     String // User can customize
+  primaryModel    String?
+  fallbackModels  Json     @default("[]")
+  toolPermissions Json     @default("[]")
+  discordChannel  String?
+  isActive        Boolean  @default(true)
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  @@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/prisma/seed.ts

@@ -7,6 +7,7 @@ import {
   EntryStatus,
   Visibility,
 } from "@prisma/client";
+import { seedAgentTemplates } from "../src/seed/agent-templates.seed";
 
 const prisma = new PrismaClient();
 
@@ -586,6 +587,9 @@ This is a draft document. See [[architecture-overview]] for current state.`,
 
     console.log(`Created ${links.length} knowledge links`);
   });
+  // Seed default agent templates (idempotent)
+  await seedAgentTemplates(prisma);
+
   console.log("Seeding completed successfully!");
 }
 

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

@@ -0,0 +1,47 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Body,
+  Param,
+  UseGuards,
+  ParseUUIDPipe,
+} from "@nestjs/common";
+import { AgentTemplateService } from "./agent-template.service";
+import { CreateAgentTemplateDto } from "./dto/create-agent-template.dto";
+import { UpdateAgentTemplateDto } from "./dto/update-agent-template.dto";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { AdminGuard } from "../auth/guards/admin.guard";
+
+@Controller("admin/agent-templates")
+@UseGuards(AuthGuard, AdminGuard)
+export class AgentTemplateController {
+  constructor(private readonly agentTemplateService: AgentTemplateService) {}
+
+  @Get()
+  findAll() {
+    return this.agentTemplateService.findAll();
+  }
+
+  @Get(":id")
+  findOne(@Param("id", ParseUUIDPipe) id: string) {
+    return this.agentTemplateService.findOne(id);
+  }
+
+  @Post()
+  create(@Body() dto: CreateAgentTemplateDto) {
+    return this.agentTemplateService.create(dto);
+  }
+
+  @Patch(":id")
+  update(@Param("id", ParseUUIDPipe) id: string, @Body() dto: UpdateAgentTemplateDto) {
+    return this.agentTemplateService.update(id, dto);
+  }
+
+  @Delete(":id")
+  remove(@Param("id", ParseUUIDPipe) id: string) {
+    return this.agentTemplateService.remove(id);
+  }
+}

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

@@ -0,0 +1,13 @@
+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, AuthModule],
+  controllers: [AgentTemplateController],
+  providers: [AgentTemplateService],
+  exports: [AgentTemplateService],
+})
+export class AgentTemplateModule {}

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

@@ -0,0 +1,57 @@
+import { Injectable, NotFoundException, ConflictException } from "@nestjs/common";
+import { PrismaService } from "../prisma/prisma.service";
+import { CreateAgentTemplateDto } from "./dto/create-agent-template.dto";
+import { UpdateAgentTemplateDto } from "./dto/update-agent-template.dto";
+
+@Injectable()
+export class AgentTemplateService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findAll() {
+    return this.prisma.agentTemplate.findMany({
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  async findOne(id: string) {
+    const template = await this.prisma.agentTemplate.findUnique({ where: { id } });
+    if (!template) throw new NotFoundException(`AgentTemplate ${id} not found`);
+    return template;
+  }
+
+  async findByName(name: string) {
+    const template = await this.prisma.agentTemplate.findUnique({ where: { name } });
+    if (!template) throw new NotFoundException(`AgentTemplate "${name}" not found`);
+    return template;
+  }
+
+  async create(dto: CreateAgentTemplateDto) {
+    const existing = await this.prisma.agentTemplate.findUnique({ where: { name: dto.name } });
+    if (existing) throw new ConflictException(`AgentTemplate "${dto.name}" already exists`);
+
+    return this.prisma.agentTemplate.create({
+      data: {
+        name: dto.name,
+        displayName: dto.displayName,
+        role: dto.role,
+        personality: dto.personality,
+        primaryModel: dto.primaryModel,
+        fallbackModels: dto.fallbackModels ?? ([] as string[]),
+        toolPermissions: dto.toolPermissions ?? ([] as string[]),
+        ...(dto.discordChannel !== undefined && { discordChannel: dto.discordChannel }),
+        isActive: dto.isActive ?? true,
+        isDefault: dto.isDefault ?? false,
+      },
+    });
+  }
+
+  async update(id: string, dto: UpdateAgentTemplateDto) {
+    await this.findOne(id);
+    return this.prisma.agentTemplate.update({ where: { id }, data: dto });
+  }
+
+  async remove(id: string) {
+    await this.findOne(id);
+    return this.prisma.agentTemplate.delete({ where: { id } });
+  }
+}

apps/api/src/agent-template/dto/create-agent-template.dto.ts

@@ -0,0 +1,43 @@
+import { IsString, IsBoolean, IsOptional, IsArray, MinLength } from "class-validator";
+
+export class CreateAgentTemplateDto {
+  @IsString()
+  @MinLength(1)
+  name!: string;
+
+  @IsString()
+  @MinLength(1)
+  displayName!: string;
+
+  @IsString()
+  @MinLength(1)
+  role!: string;
+
+  @IsString()
+  @MinLength(1)
+  personality!: string;
+
+  @IsString()
+  @MinLength(1)
+  primaryModel!: string;
+
+  @IsArray()
+  @IsOptional()
+  fallbackModels?: string[];
+
+  @IsArray()
+  @IsOptional()
+  toolPermissions?: string[];
+
+  @IsString()
+  @IsOptional()
+  discordChannel?: string;
+
+  @IsBoolean()
+  @IsOptional()
+  isActive?: boolean;
+
+  @IsBoolean()
+  @IsOptional()
+  isDefault?: boolean;
+}

apps/api/src/agent-template/dto/update-agent-template.dto.ts

@@ -0,0 +1,4 @@
+import { PartialType } from "@nestjs/mapped-types";
+import { CreateAgentTemplateDto } from "./create-agent-template.dto";
+
+export class UpdateAgentTemplateDto extends PartialType(CreateAgentTemplateDto) {}

apps/api/src/app.module.ts

@@ -48,6 +48,8 @@ import { TerminalModule } from "./terminal/terminal.module";
 import { PersonalitiesModule } from "./personalities/personalities.module";
 import { WorkspacesModule } from "./workspaces/workspaces.module";
 import { AdminModule } from "./admin/admin.module";
+import { AgentTemplateModule } from "./agent-template/agent-template.module";
+import { UserAgentModule } from "./user-agent/user-agent.module";
 import { TeamsModule } from "./teams/teams.module";
 import { ImportModule } from "./import/import.module";
 import { ConversationArchiveModule } from "./conversation-archive/conversation-archive.module";
@@ -129,6 +131,8 @@ import { OrchestratorModule } from "./orchestrator/orchestrator.module";
     PersonalitiesModule,
     WorkspacesModule,
     AdminModule,
+    AgentTemplateModule,
+    UserAgentModule,
     TeamsModule,
     ImportModule,
     ConversationArchiveModule,

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.controller.ts

@@ -1,31 +1,79 @@
-import {
-  Body,
-  Controller,
-  HttpException,
-  Logger,
-  Post,
-  Req,
-  Res,
-  UnauthorizedException,
-  UseGuards,
-} from "@nestjs/common";
+import { Body, Controller, HttpException, Logger, Post, Req, Res, UseGuards } from "@nestjs/common";
 import type { Response } from "express";
 import { AuthGuard } from "../auth/guards/auth.guard";
+import { SkipCsrf } from "../common/decorators/skip-csrf.decorator";
 import type { MaybeAuthenticatedRequest } from "../auth/types/better-auth-request.interface";
 import { ChatStreamDto } from "./chat-proxy.dto";
 import { ChatProxyService } from "./chat-proxy.service";
 
 @Controller("chat")
-@UseGuards(AuthGuard)
 export class ChatProxyController {
   private readonly logger = new Logger(ChatProxyController.name);
 
   constructor(private readonly chatProxyService: ChatProxyService) {}
 
+  // POST /api/chat/guest
+  // Guest chat endpoint - no authentication required
+  // Uses a shared LLM configuration for unauthenticated users
+  @SkipCsrf()
+  @Post("guest")
+  async guestChat(
+    @Body() body: ChatStreamDto,
+    @Req() req: MaybeAuthenticatedRequest,
+    @Res() res: Response
+  ): Promise<void> {
+    const abortController = new AbortController();
+    req.once("close", () => {
+      abortController.abort();
+    });
+
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+
+    try {
+      const upstreamResponse = await this.chatProxyService.proxyGuestChat(
+        body.messages,
+        abortController.signal
+      );
+
+      const upstreamContentType = upstreamResponse.headers.get("content-type");
+      if (upstreamContentType) {
+        res.setHeader("Content-Type", upstreamContentType);
+      }
+
+      if (!upstreamResponse.body) {
+        throw new Error("LLM response did not include a stream body");
+      }
+
+      for await (const chunk of upstreamResponse.body as unknown as AsyncIterable<Uint8Array>) {
+        if (res.writableEnded || res.destroyed) {
+          break;
+        }
+
+        res.write(Buffer.from(chunk));
+      }
+    } catch (error: unknown) {
+      this.logStreamError(error);
+
+      if (!res.writableEnded && !res.destroyed) {
+        res.write("event: error\n");
+        res.write(`data: ${JSON.stringify({ error: this.toSafeClientMessage(error) })}\n\n`);
+      }
+    } finally {
+      if (!res.writableEnded && !res.destroyed) {
+        res.end();
+      }
+    }
+  }
+
   // POST /api/chat/stream
   // Request: { messages: Array<{role, content}> }
   // Response: SSE stream of chat completion events
+  // Requires authentication - uses user's personal OpenClaw container
   @Post("stream")
+  @UseGuards(AuthGuard)
   async streamChat(
     @Body() body: ChatStreamDto,
     @Req() req: MaybeAuthenticatedRequest,
@@ -33,7 +81,8 @@ export class ChatProxyController {
   ): Promise<void> {
     const userId = req.user?.id;
     if (!userId) {
-      throw new UnauthorizedException("No authenticated user found on request");
+      this.logger.warn("streamChat called without user ID after AuthGuard");
+      throw new HttpException("Authentication required", 401);
     }
 
     const abortController = new AbortController();
@@ -50,7 +99,8 @@ export class ChatProxyController {
       const upstreamResponse = await this.chatProxyService.proxyChat(
         userId,
         body.messages,
-        abortController.signal
+        abortController.signal,
+        body.agent
       );
 
       const upstreamContentType = upstreamResponse.headers.get("content-type");

apps/api/src/chat-proxy/chat-proxy.dto.ts

@@ -1,5 +1,12 @@
 import { Type } from "class-transformer";
-import { ArrayMinSize, IsArray, IsNotEmpty, IsString, ValidateNested } from "class-validator";
+import {
+  ArrayMinSize,
+  IsArray,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from "class-validator";
 
 export interface ChatMessage {
   role: string;
@@ -22,4 +29,8 @@ export class ChatStreamDto {
   @ValidateNested({ each: true })
   @Type(() => ChatMessageDto)
   messages!: ChatMessageDto[];
+
+  @IsString({ message: "agent must be a string" })
+  @IsOptional()
+  agent?: string;
 }

apps/api/src/chat-proxy/chat-proxy.module.ts

@@ -1,4 +1,5 @@
 import { Module } from "@nestjs/common";
+import { ConfigModule } from "@nestjs/config";
 import { AuthModule } from "../auth/auth.module";
 import { AgentConfigModule } from "../agent-config/agent-config.module";
 import { ContainerLifecycleModule } from "../container-lifecycle/container-lifecycle.module";
@@ -7,7 +8,7 @@ import { ChatProxyController } from "./chat-proxy.controller";
 import { ChatProxyService } from "./chat-proxy.service";
 
 @Module({
-  imports: [AuthModule, PrismaModule, ContainerLifecycleModule, AgentConfigModule],
+  imports: [AuthModule, PrismaModule, ContainerLifecycleModule, AgentConfigModule, ConfigModule],
   controllers: [ChatProxyController],
   providers: [ChatProxyService],
   exports: [ChatProxyService],

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/chat-proxy/chat-proxy.service.ts

@@ -2,26 +2,38 @@ import {
   BadGatewayException,
   Injectable,
   Logger,
+  NotFoundException,
   ServiceUnavailableException,
 } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
 import { ContainerLifecycleService } from "../container-lifecycle/container-lifecycle.service";
 import { PrismaService } from "../prisma/prisma.service";
 import type { ChatMessage } from "./chat-proxy.dto";
 
 const DEFAULT_OPENCLAW_MODEL = "openclaw:default";
+const DEFAULT_GUEST_LLM_URL = "http://10.1.1.42:11434/v1";
+const DEFAULT_GUEST_LLM_MODEL = "llama3.2";
 
 interface ContainerConnection {
   url: string;
   token: string;
 }
 
+interface AgentConfig {
+  name: string;
+  displayName: string;
+  personality: string;
+  primaryModel: string | null;
+}
+
 @Injectable()
 export class ChatProxyService {
   private readonly logger = new Logger(ChatProxyService.name);
 
   constructor(
     private readonly prisma: PrismaService,
-    private readonly containerLifecycle: ContainerLifecycleService
+    private readonly containerLifecycle: ContainerLifecycleService,
+    private readonly config: ConfigService
   ) {}
 
   // Get the user's OpenClaw container URL and mark it active.
@@ -34,21 +46,38 @@ export class ChatProxyService {
   async proxyChat(
     userId: string,
     messages: ChatMessage[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    agentName?: string
   ): Promise<Response> {
     const { url: containerUrl, token: gatewayToken } = await this.getContainerConnection(userId);
-    const model = await this.getPreferredModel(userId);
+
+    // Get agent config if specified
+    let agentConfig: AgentConfig | null = null;
+    if (agentName) {
+      agentConfig = await this.getAgentConfig(userId, agentName);
+    }
+
+    const model = agentConfig?.primaryModel ?? (await this.getPreferredModel(userId));
+
+    const requestBody: Record<string, unknown> = {
+      messages,
+      model,
+      stream: true,
+    };
+
+    // Add agent config if available
+    if (agentConfig) {
+      requestBody.agent = agentConfig.name;
+      requestBody.agent_personality = agentConfig.personality;
+    }
+
     const requestInit: RequestInit = {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${gatewayToken}`,
       },
-      body: JSON.stringify({
-        messages,
-        model,
-        stream: true,
-      }),
+      body: JSON.stringify(requestBody),
     };
 
     if (signal) {
@@ -79,6 +108,65 @@ export class ChatProxyService {
     }
   }
 
+  /**
+   * Proxy guest chat request to configured LLM endpoint.
+   * Uses environment variables for configuration:
+   * - GUEST_LLM_URL: OpenAI-compatible endpoint URL
+   * - GUEST_LLM_API_KEY: API key (optional, for cloud providers)
+   * - GUEST_LLM_MODEL: Model name to use
+   */
+  async proxyGuestChat(messages: ChatMessage[], signal?: AbortSignal): Promise<Response> {
+    const llmUrl = this.config.get<string>("GUEST_LLM_URL") ?? DEFAULT_GUEST_LLM_URL;
+    const llmApiKey = this.config.get<string>("GUEST_LLM_API_KEY");
+    const llmModel = this.config.get<string>("GUEST_LLM_MODEL") ?? DEFAULT_GUEST_LLM_MODEL;
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (llmApiKey) {
+      headers.Authorization = `Bearer ${llmApiKey}`;
+    }
+
+    const requestInit: RequestInit = {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        messages,
+        model: llmModel,
+        stream: true,
+      }),
+    };
+
+    if (signal) {
+      requestInit.signal = signal;
+    }
+
+    try {
+      this.logger.debug(`Guest chat proxying to ${llmUrl} with model ${llmModel}`);
+      const response = await fetch(`${llmUrl}/chat/completions`, requestInit);
+
+      if (!response.ok) {
+        const detail = await this.readResponseText(response);
+        const status = `${String(response.status)} ${response.statusText}`.trim();
+        this.logger.warn(
+          detail ? `Guest LLM returned ${status}: ${detail}` : `Guest LLM returned ${status}`
+        );
+        throw new BadGatewayException(`Guest LLM returned ${status}`);
+      }
+
+      return response;
+    } catch (error: unknown) {
+      if (error instanceof BadGatewayException) {
+        throw error;
+      }
+
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`Failed to proxy guest chat request: ${message}`);
+      throw new ServiceUnavailableException("Failed to proxy guest chat to LLM");
+    }
+  }
+
   private async getContainerConnection(userId: string): Promise<ContainerConnection> {
     const connection = await this.containerLifecycle.ensureRunning(userId);
     await this.containerLifecycle.touch(userId);
@@ -107,4 +195,32 @@ export class ChatProxyService {
       return null;
     }
   }
+
+  private async getAgentConfig(userId: string, agentName: string): Promise<AgentConfig> {
+    const agent = await this.prisma.userAgent.findUnique({
+      where: { userId_name: { userId, name: agentName } },
+      select: {
+        name: true,
+        displayName: true,
+        personality: true,
+        primaryModel: true,
+        isActive: true,
+      },
+    });
+
+    if (!agent) {
+      throw new NotFoundException(`Agent "${agentName}" not found for user`);
+    }
+
+    if (!agent.isActive) {
+      throw new NotFoundException(`Agent "${agentName}" is not active`);
+    }
+
+    return {
+      name: agent.name,
+      displayName: agent.displayName,
+      personality: agent.personality,
+      primaryModel: agent.primaryModel,
+    };
+  }
 }

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

@@ -1,4 +1,4 @@
-import { Controller, Get, Res, UseGuards } from "@nestjs/common";
+import { Controller, Get, Query, Res, UseGuards } from "@nestjs/common";
 import { AgentStatus } from "@prisma/client";
 import type { Response } from "express";
 import { AuthGuard } from "../auth/guards/auth.guard";
@@ -6,6 +6,7 @@ import { PrismaService } from "../prisma/prisma.service";
 
 const AGENT_POLL_INTERVAL_MS = 5_000;
 const SSE_HEARTBEAT_MS = 15_000;
+const DEFAULT_EVENTS_LIMIT = 25;
 
 interface OrchestratorAgentDto {
   id: string;
@@ -15,6 +16,26 @@ interface OrchestratorAgentDto {
   createdAt: Date;
 }
 
+interface OrchestratorEventDto {
+  type: string;
+  timestamp: string;
+  agentId?: string;
+  taskId?: string;
+  data?: Record<string, unknown>;
+}
+
+interface OrchestratorHealthDto {
+  status: "healthy" | "degraded" | "unhealthy";
+  database: "connected" | "disconnected";
+  agents: {
+    total: number;
+    working: number;
+    idle: number;
+    errored: number;
+  };
+  timestamp: string;
+}
+
 @Controller("orchestrator")
 @UseGuards(AuthGuard)
 export class OrchestratorController {
@@ -25,6 +46,81 @@ export class OrchestratorController {
     return this.fetchActiveAgents();
   }
 
+  @Get("events/recent")
+  async getRecentEvents(
+    @Query("limit") limit?: string
+  ): Promise<{ events: OrchestratorEventDto[] }> {
+    const eventsLimit = limit ? parseInt(limit, 10) : DEFAULT_EVENTS_LIMIT;
+    const safeLimit = Math.min(Math.max(eventsLimit, 1), 100);
+
+    // Fetch recent agent activity to derive events
+    const agents = await this.prisma.agent.findMany({
+      where: {
+        status: {
+          not: AgentStatus.TERMINATED,
+        },
+      },
+      orderBy: {
+        createdAt: "desc",
+      },
+      take: safeLimit,
+    });
+
+    // Derive events from agent status changes
+    const events: OrchestratorEventDto[] = agents.map((agent) => ({
+      type: `agent:${agent.status.toLowerCase()}`,
+      timestamp: agent.createdAt.toISOString(),
+      agentId: agent.id,
+      data: {
+        name: agent.name,
+        role: agent.role,
+        model: agent.model,
+      },
+    }));
+
+    return { events };
+  }
+
+  @Get("health")
+  async getHealth(): Promise<OrchestratorHealthDto> {
+    let databaseConnected = false;
+    let agents: OrchestratorAgentDto[] = [];
+
+    try {
+      // Check database connectivity
+      await this.prisma.$queryRaw`SELECT 1`;
+      databaseConnected = true;
+
+      // Get agent counts
+      agents = await this.fetchActiveAgents();
+    } catch {
+      databaseConnected = false;
+    }
+
+    const working = agents.filter((a) => a.status === AgentStatus.WORKING).length;
+    const idle = agents.filter((a) => a.status === AgentStatus.IDLE).length;
+    const errored = agents.filter((a) => a.status === AgentStatus.ERROR).length;
+
+    let status: OrchestratorHealthDto["status"] = "healthy";
+    if (!databaseConnected) {
+      status = "unhealthy";
+    } else if (errored > 0) {
+      status = "degraded";
+    }
+
+    return {
+      status,
+      database: databaseConnected ? "connected" : "disconnected",
+      agents: {
+        total: agents.length,
+        working,
+        idle,
+        errored,
+      },
+      timestamp: new Date().toISOString(),
+    };
+  }
+
   @Get("events")
   async streamEvents(@Res() res: Response): Promise<void> {
     res.setHeader("Content-Type", "text/event-stream");

apps/api/src/seed/agent-templates.seed.ts

@@ -0,0 +1,62 @@
+import type { PrismaClient } from "@prisma/client";
+
+const AGENT_TEMPLATES = [
+  {
+    name: "jarvis",
+    displayName: "Jarvis",
+    role: "orchestrator",
+    personality: `# Jarvis - Orchestrator Agent\n\nYou are Jarvis, the orchestrator and COO. You plan, delegate, and coordinate. You never write code directly — you spawn workers. You are direct, capable, and proactive. Your job is to get things done without hand-holding.\n\n## Core Traits\n- Direct and concise\n- Resourceful — figure it out before asking\n- Proactive — find problems to solve\n- Delegator — workers execute, you orchestrate`,
+    primaryModel: "opus",
+    fallbackModels: ["sonnet"],
+    toolPermissions: ["read", "write", "exec", "browser", "web_search", "memory_search"],
+    discordChannel: "jarvis",
+    isActive: true,
+    isDefault: true,
+  },
+  {
+    name: "builder",
+    displayName: "Builder",
+    role: "coding",
+    personality: `# Builder - Coding Agent\n\nYou are Builder, the coding agent. You implement features, fix bugs, and write tests. You work in worktrees, follow the E2E delivery protocol, and never skip quality gates. You are methodical and thorough.\n\n## Core Traits\n- Works in git worktrees (never touches main directly)\n- Runs lint + typecheck + tests before every commit\n- Follows the Mosaic E2E delivery framework\n- Never marks a task done until CI is green`,
+    primaryModel: "codex",
+    fallbackModels: ["sonnet", "haiku"],
+    toolPermissions: ["read", "write", "exec"],
+    discordChannel: "builder",
+    isActive: true,
+    isDefault: true,
+  },
+  {
+    name: "medic",
+    displayName: "Medic",
+    role: "monitoring",
+    personality: `# Medic - Health Monitoring Agent\n\nYou are Medic, the health monitoring agent. You watch services, check deployments, alert on anomalies, and verify system health. You are vigilant, calm, and proactive.\n\n## Core Traits\n- Monitors service health proactively\n- Alerts clearly and concisely\n- Tracks uptime and deployment status\n- Never panics — diagnoses methodically`,
+    primaryModel: "haiku",
+    fallbackModels: ["sonnet"],
+    toolPermissions: ["read", "exec"],
+    discordChannel: "medic-alerts",
+    isActive: true,
+    isDefault: true,
+  },
+];
+
+export async function seedAgentTemplates(prisma: PrismaClient): Promise<void> {
+  for (const template of AGENT_TEMPLATES) {
+    await prisma.agentTemplate.upsert({
+      where: { name: template.name },
+      update: {},
+      create: {
+        name: template.name,
+        displayName: template.displayName,
+        role: template.role,
+        personality: template.personality,
+        primaryModel: template.primaryModel,
+        fallbackModels: template.fallbackModels,
+        toolPermissions: template.toolPermissions,
+        discordChannel: template.discordChannel,
+        isActive: template.isActive,
+        isDefault: template.isDefault,
+      },
+    });
+  }
+  console.log("✅ Agent templates seeded:", AGENT_TEMPLATES.map((t) => t.name).join(", "));
+}

apps/api/src/user-agent/dto/create-user-agent.dto.ts

@@ -0,0 +1,43 @@
+import { IsString, IsBoolean, IsOptional, IsArray, MinLength } from "class-validator";
+
+export class CreateUserAgentDto {
+  @IsString()
+  @MinLength(1)
+  templateId?: string;
+
+  @IsString()
+  @MinLength(1)
+  name!: string;
+
+  @IsString()
+  @MinLength(1)
+  displayName!: string;
+
+  @IsString()
+  @MinLength(1)
+  role!: string;
+
+  @IsString()
+  @MinLength(1)
+  personality!: string;
+
+  @IsString()
+  @IsOptional()
+  primaryModel?: string;
+
+  @IsArray()
+  @IsOptional()
+  fallbackModels?: string[];
+
+  @IsArray()
+  @IsOptional()
+  toolPermissions?: string[];
+
+  @IsString()
+  @IsOptional()
+  discordChannel?: string;
+
+  @IsBoolean()
+  @IsOptional()
+  isActive?: boolean;
+}

apps/api/src/user-agent/dto/update-user-agent.dto.ts

@@ -0,0 +1,4 @@
+import { PartialType } from "@nestjs/mapped-types";
+import { CreateUserAgentDto } from "./create-user-agent.dto";
+
+export class UpdateUserAgentDto extends PartialType(CreateUserAgentDto) {}

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

@@ -0,0 +1,70 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Body,
+  Param,
+  UseGuards,
+  ParseUUIDPipe,
+} from "@nestjs/common";
+import { UserAgentService } from "./user-agent.service";
+import { CreateUserAgentDto } from "./dto/create-user-agent.dto";
+import { UpdateUserAgentDto } from "./dto/update-user-agent.dto";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+import type { AuthUser } from "@mosaic/shared";
+
+@Controller("agents")
+@UseGuards(AuthGuard)
+export class UserAgentController {
+  constructor(private readonly userAgentService: UserAgentService) {}
+
+  @Get()
+  findAll(@CurrentUser() user: AuthUser) {
+    return this.userAgentService.findAll(user.id);
+  }
+
+  @Get("status")
+  getAllStatuses(@CurrentUser() user: AuthUser) {
+    return this.userAgentService.getAllStatuses(user.id);
+  }
+
+  @Get(":id")
+  findOne(@CurrentUser() user: AuthUser, @Param("id", ParseUUIDPipe) id: string) {
+    return this.userAgentService.findOne(user.id, id);
+  }
+
+  @Get(":id/status")
+  getStatus(@CurrentUser() user: AuthUser, @Param("id", ParseUUIDPipe) id: string) {
+    return this.userAgentService.getStatus(user.id, id);
+  }
+
+  @Post()
+  create(@CurrentUser() user: AuthUser, @Body() dto: CreateUserAgentDto) {
+    return this.userAgentService.create(user.id, dto);
+  }
+
+  @Post("from-template/:templateId")
+  createFromTemplate(
+    @CurrentUser() user: AuthUser,
+    @Param("templateId", ParseUUIDPipe) templateId: string
+  ) {
+    return this.userAgentService.createFromTemplate(user.id, templateId);
+  }
+
+  @Patch(":id")
+  update(
+    @CurrentUser() user: AuthUser,
+    @Param("id", ParseUUIDPipe) id: string,
+    @Body() dto: UpdateUserAgentDto
+  ) {
+    return this.userAgentService.update(user.id, id, dto);
+  }
+
+  @Delete(":id")
+  remove(@CurrentUser() user: AuthUser, @Param("id", ParseUUIDPipe) id: string) {
+    return this.userAgentService.remove(user.id, id);
+  }
+}

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

@@ -0,0 +1,13 @@
+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, AuthModule],
+  controllers: [UserAgentController],
+  providers: [UserAgentService],
+  exports: [UserAgentService],
+})
+export class UserAgentModule {}

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/api/src/user-agent/user-agent.service.ts

@@ -0,0 +1,153 @@
+import {
+  Injectable,
+  NotFoundException,
+  ConflictException,
+  ForbiddenException,
+} from "@nestjs/common";
+import { PrismaService } from "../prisma/prisma.service";
+import { CreateUserAgentDto } from "./dto/create-user-agent.dto";
+import { UpdateUserAgentDto } from "./dto/update-user-agent.dto";
+
+export interface AgentStatusResponse {
+  id: string;
+  name: string;
+  displayName: string;
+  role: string;
+  isActive: boolean;
+  containerStatus?: "running" | "stopped" | "unknown";
+}
+
+@Injectable()
+export class UserAgentService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findAll(userId: string) {
+    return this.prisma.userAgent.findMany({
+      where: { userId },
+      orderBy: { createdAt: "asc" },
+    });
+  }
+
+  async findOne(userId: string, id: string) {
+    const agent = await this.prisma.userAgent.findUnique({ where: { id } });
+    if (!agent) throw new NotFoundException(`UserAgent ${id} not found`);
+    if (agent.userId !== userId) throw new ForbiddenException("Access denied to this agent");
+    return agent;
+  }
+
+  async findByName(userId: string, name: string) {
+    const agent = await this.prisma.userAgent.findUnique({
+      where: { userId_name: { userId, name } },
+    });
+    if (!agent) throw new NotFoundException(`UserAgent "${name}" not found for user`);
+    return agent;
+  }
+
+  async create(userId: string, dto: CreateUserAgentDto) {
+    // Check for unique name within user scope
+    const existing = await this.prisma.userAgent.findUnique({
+      where: { userId_name: { userId, name: dto.name } },
+    });
+    if (existing)
+      throw new ConflictException(`UserAgent "${dto.name}" already exists for this user`);
+
+    // If templateId provided, verify it exists
+    if (dto.templateId) {
+      const template = await this.prisma.agentTemplate.findUnique({
+        where: { id: dto.templateId },
+      });
+      if (!template) throw new NotFoundException(`AgentTemplate ${dto.templateId} not found`);
+    }
+
+    return this.prisma.userAgent.create({
+      data: {
+        userId,
+        templateId: dto.templateId ?? null,
+        name: dto.name,
+        displayName: dto.displayName,
+        role: dto.role,
+        personality: dto.personality,
+        primaryModel: dto.primaryModel ?? null,
+        fallbackModels: dto.fallbackModels ?? ([] as string[]),
+        toolPermissions: dto.toolPermissions ?? ([] as string[]),
+        discordChannel: dto.discordChannel ?? null,
+        isActive: dto.isActive ?? true,
+      },
+    });
+  }
+
+  async createFromTemplate(userId: string, templateId: string) {
+    const template = await this.prisma.agentTemplate.findUnique({
+      where: { id: templateId },
+    });
+    if (!template) throw new NotFoundException(`AgentTemplate ${templateId} not found`);
+
+    // Check for unique name within user scope
+    const existing = await this.prisma.userAgent.findUnique({
+      where: { userId_name: { userId, name: template.name } },
+    });
+    if (existing)
+      throw new ConflictException(`UserAgent "${template.name}" already exists for this user`);
+
+    return this.prisma.userAgent.create({
+      data: {
+        userId,
+        templateId: template.id,
+        name: template.name,
+        displayName: template.displayName,
+        role: template.role,
+        personality: template.personality,
+        primaryModel: template.primaryModel,
+        fallbackModels: template.fallbackModels as string[],
+        toolPermissions: template.toolPermissions as string[],
+        discordChannel: template.discordChannel,
+        isActive: template.isActive,
+      },
+    });
+  }
+
+  async update(userId: string, id: string, dto: UpdateUserAgentDto) {
+    const agent = await this.findOne(userId, id);
+
+    // If name is being changed, check for uniqueness
+    if (dto.name && dto.name !== agent.name) {
+      const existing = await this.prisma.userAgent.findUnique({
+        where: { userId_name: { userId, name: dto.name } },
+      });
+      if (existing)
+        throw new ConflictException(`UserAgent "${dto.name}" already exists for this user`);
+    }
+
+    return this.prisma.userAgent.update({
+      where: { id },
+      data: dto,
+    });
+  }
+
+  async remove(userId: string, id: string) {
+    await this.findOne(userId, id);
+    return this.prisma.userAgent.delete({ where: { id } });
+  }
+
+  async getStatus(userId: string, id: string): Promise<AgentStatusResponse> {
+    const agent = await this.findOne(userId, id);
+    return {
+      id: agent.id,
+      name: agent.name,
+      displayName: agent.displayName,
+      role: agent.role,
+      isActive: agent.isActive,
+    };
+  }
+
+  async getAllStatuses(userId: string): Promise<AgentStatusResponse[]> {
+    const agents = await this.findAll(userId);
+    return agents.map((agent) => ({
+      id: agent.id,
+      name: agent.name,
+      displayName: agent.displayName,
+      role: agent.role,
+      isActive: agent.isActive,
+    }));
+  }
+}

apps/coordinator/tests/test_coordinator.py

@@ -601,9 +601,21 @@ class TestCoordinatorIntegration:
         coordinator = Coordinator(queue_manager=queue_manager, poll_interval=0.02)
 
         task = asyncio.create_task(coordinator.start())
-        await asyncio.sleep(0.5)  # Allow time for processing
-        await coordinator.stop()
 
+        # Poll for completion with timeout instead of fixed sleep
+        deadline = asyncio.get_event_loop().time() + 5.0  # 5 second timeout
+        while asyncio.get_event_loop().time() < deadline:
+            all_completed = True
+            for i in range(157, 162):
+                item = queue_manager.get_item(i)
+                if item is None or item.status != QueueItemStatus.COMPLETED:
+                    all_completed = False
+                    break
+            if all_completed:
+                break
+            await asyncio.sleep(0.05)
+
+        await coordinator.stop()
         task.cancel()
         try:
             await task

apps/orchestrator/Dockerfile

@@ -21,6 +21,10 @@ 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 ./
 
 # Install ALL dependencies (not just production)
 # No cache mount — Kaniko builds are ephemeral in CI
@@ -43,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,30 +3,33 @@
   "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",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix"
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.72.1",
     "@mosaic/config": "workspace:*",
     "@mosaic/shared": "workspace:*",
+    "@nestjs/axios": "^4.0.1",
     "@nestjs/bullmq": "^11.0.4",
     "@nestjs/common": "^11.1.12",
     "@nestjs/config": "^4.0.2",
     "@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 +48,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-audit-log-query.dto.ts

@@ -0,0 +1,21 @@
+import { Type } from "class-transformer";
+import { IsInt, IsOptional, IsString, Max, Min } from "class-validator";
+
+export class GetMissionControlAuditLogQueryDto {
+  @IsOptional()
+  @IsString()
+  sessionId?: string;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(200)
+  limit = 50;
+}

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.spec.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentSession } from "@mosaic/shared";
+import type { PrismaService } from "../../prisma/prisma.service";
+import { AgentProviderRegistry } from "../agents/agent-provider.registry";
+import { MissionControlController } from "./mission-control.controller";
+import { MissionControlService } from "./mission-control.service";
+
+describe("MissionControlController", () => {
+  let controller: MissionControlController;
+  let registry: {
+    listAllSessions: ReturnType<typeof vi.fn>;
+    getProviderForSession: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    registry = {
+      listAllSessions: vi.fn(),
+      getProviderForSession: vi.fn(),
+    };
+
+    const prisma = {
+      operatorAuditLog: {
+        create: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+
+    const service = new MissionControlService(
+      registry as unknown as AgentProviderRegistry,
+      prisma as unknown as PrismaService
+    );
+
+    controller = new MissionControlController(service);
+  });
+
+  it("Phase 1 gate: unified sessions endpoint returns internal provider sessions", async () => {
+    const internalSession: AgentSession = {
+      id: "session-internal-1",
+      providerId: "internal",
+      providerType: "internal",
+      status: "active",
+      createdAt: new Date("2026-03-07T20:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T20:01:00.000Z"),
+    };
+
+    const externalSession: AgentSession = {
+      id: "session-openclaw-1",
+      providerId: "openclaw",
+      providerType: "external",
+      status: "active",
+      createdAt: new Date("2026-03-07T20:02:00.000Z"),
+      updatedAt: new Date("2026-03-07T20:03:00.000Z"),
+    };
+
+    registry.listAllSessions.mockResolvedValue([internalSession, externalSession]);
+
+    const response = await controller.listSessions();
+
+    expect(registry.listAllSessions).toHaveBeenCalledTimes(1);
+    expect(response.sessions).toEqual([internalSession, externalSession]);
+    expect(response.sessions).toContainEqual(
+      expect.objectContaining({
+        id: "session-internal-1",
+        providerId: "internal",
+      })
+    );
+  });
+});

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

@@ -0,0 +1,192 @@
+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 { GetMissionControlAuditLogQueryDto } from "./dto/get-mission-control-audit-log-query.dto";
+import { GetMissionControlMessagesQueryDto } from "./dto/get-mission-control-messages-query.dto";
+import { KillSessionDto } from "./dto/kill-session.dto";
+import { MissionControlService, type MissionControlAuditLogPage } 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 };
+  }
+
+  @Get("audit-log")
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  getAuditLog(
+    @Query() query: GetMissionControlAuditLogQueryDto
+  ): Promise<MissionControlAuditLogPage> {
+    return this.missionControlService.getAuditLog(query.sessionId, query.page, query.limit);
+  }
+
+  @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,186 @@
+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";
+
+export interface AuditLogEntry {
+  id: string;
+  userId: string;
+  sessionId: string;
+  provider: string;
+  action: string;
+  content: string | null;
+  metadata: Prisma.JsonValue;
+  createdAt: Date;
+}
+
+export interface MissionControlAuditLogPage {
+  items: AuditLogEntry[];
+  total: number;
+  page: number;
+  pages: number;
+}
+
+@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 getAuditLog(
+    sessionId: string | undefined,
+    page: number,
+    limit: number
+  ): Promise<MissionControlAuditLogPage> {
+    const normalizedSessionId = sessionId?.trim();
+    const where: Prisma.OperatorAuditLogWhereInput =
+      normalizedSessionId && normalizedSessionId.length > 0
+        ? { sessionId: normalizedSessionId }
+        : {};
+
+    const [total, items] = await this.prisma.$transaction([
+      this.prisma.operatorAuditLog.count({ where }),
+      this.prisma.operatorAuditLog.findMany({
+        where,
+        orderBy: { createdAt: "desc" },
+        skip: (page - 1) * limit,
+        take: limit,
+      }),
+    ]);
+
+    return {
+      items,
+      total,
+      page,
+      pages: total === 0 ? 0 : Math.ceil(total / limit),
+    };
+  }
+
+  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/api/providers/openclaw/openclaw.provider-factory.ts

@@ -0,0 +1,17 @@
+import { HttpService } from "@nestjs/axios";
+import { Injectable } from "@nestjs/common";
+import type { AgentProviderConfig } from "@prisma/client";
+import { EncryptionService } from "../../../security/encryption.service";
+import { OpenClawProvider } from "./openclaw.provider";
+
+@Injectable()
+export class OpenClawProviderFactory {
+  constructor(
+    private readonly encryptionService: EncryptionService,
+    private readonly httpService: HttpService
+  ) {}
+
+  createProvider(config: AgentProviderConfig): OpenClawProvider {
+    return new OpenClawProvider(config, this.encryptionService, this.httpService);
+  }
+}

apps/orchestrator/src/api/providers/openclaw/openclaw.provider.spec.ts

@@ -0,0 +1,270 @@
+import type { HttpService } from "@nestjs/axios";
+import { ServiceUnavailableException } from "@nestjs/common";
+import type { AgentProviderConfig } from "@prisma/client";
+import { Readable } from "node:stream";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EncryptionService } from "../../../security/encryption.service";
+import { OpenClawProvider } from "./openclaw.provider";
+
+describe("OpenClawProvider", () => {
+  let provider: OpenClawProvider;
+  let httpService: {
+    axiosRef: {
+      get: ReturnType<typeof vi.fn>;
+      post: ReturnType<typeof vi.fn>;
+    };
+  };
+  let encryptionService: {
+    decryptIfNeeded: ReturnType<typeof vi.fn>;
+  };
+
+  const config: AgentProviderConfig = {
+    id: "cfg-openclaw-1",
+    workspaceId: "workspace-1",
+    name: "openclaw-home",
+    provider: "openclaw",
+    gatewayUrl: "https://gateway.example.com/",
+    credentials: {
+      apiToken: "enc:token-value",
+      displayName: "Home OpenClaw",
+    },
+    isActive: true,
+    createdAt: new Date("2026-03-07T15:00:00.000Z"),
+    updatedAt: new Date("2026-03-07T15:00:00.000Z"),
+  };
+
+  beforeEach(() => {
+    httpService = {
+      axiosRef: {
+        get: vi.fn(),
+        post: vi.fn(),
+      },
+    };
+
+    encryptionService = {
+      decryptIfNeeded: vi.fn().mockReturnValue("plain-token"),
+    };
+
+    provider = new OpenClawProvider(
+      config,
+      encryptionService as unknown as EncryptionService,
+      httpService as unknown as HttpService
+    );
+  });
+
+  it("maps listSessions from OpenClaw API", async () => {
+    httpService.axiosRef.get.mockResolvedValue({
+      data: {
+        sessions: [
+          {
+            id: "session-1",
+            status: "running",
+            createdAt: "2026-03-07T15:01:00.000Z",
+            updatedAt: "2026-03-07T15:02:00.000Z",
+          },
+        ],
+        total: 1,
+        cursor: "next-cursor",
+      },
+    });
+
+    const result = await provider.listSessions("cursor-1", 25);
+
+    expect(httpService.axiosRef.get).toHaveBeenCalledWith(
+      "https://gateway.example.com/api/sessions",
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+        params: {
+          cursor: "cursor-1",
+          limit: 25,
+        },
+      }
+    );
+    expect(result).toEqual({
+      sessions: [
+        {
+          id: "session-1",
+          providerId: "openclaw-home",
+          providerType: "openclaw",
+          status: "active",
+          createdAt: new Date("2026-03-07T15:01:00.000Z"),
+          updatedAt: new Date("2026-03-07T15:02:00.000Z"),
+        },
+      ],
+      total: 1,
+      cursor: "next-cursor",
+    });
+    expect(encryptionService.decryptIfNeeded).toHaveBeenCalledWith("enc:token-value");
+  });
+
+  it("returns null from getSession when OpenClaw returns 404", async () => {
+    httpService.axiosRef.get.mockRejectedValue({
+      response: {
+        status: 404,
+      },
+    });
+
+    await expect(provider.getSession("missing-session")).resolves.toBeNull();
+  });
+
+  it("maps getMessages response", async () => {
+    httpService.axiosRef.get.mockResolvedValue({
+      data: {
+        messages: [
+          {
+            id: "message-1",
+            sessionId: "session-1",
+            role: "agent",
+            content: "hello",
+            timestamp: "2026-03-07T15:03:00.000Z",
+            metadata: {
+              tokens: 128,
+            },
+          },
+        ],
+      },
+    });
+
+    const result = await provider.getMessages("session-1", 20, "before-cursor");
+
+    expect(httpService.axiosRef.get).toHaveBeenCalledWith(
+      "https://gateway.example.com/api/messages",
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+        params: {
+          sessionId: "session-1",
+          limit: 20,
+          before: "before-cursor",
+        },
+      }
+    );
+    expect(result).toEqual([
+      {
+        id: "message-1",
+        sessionId: "session-1",
+        role: "assistant",
+        content: "hello",
+        timestamp: new Date("2026-03-07T15:03:00.000Z"),
+        metadata: {
+          tokens: 128,
+        },
+      },
+    ]);
+  });
+
+  it("maps inject and control endpoints", async () => {
+    httpService.axiosRef.post
+      .mockResolvedValueOnce({
+        data: {
+          accepted: true,
+          messageId: "message-2",
+        },
+      })
+      .mockResolvedValueOnce({ data: {} })
+      .mockResolvedValueOnce({ data: {} })
+      .mockResolvedValueOnce({ data: {} });
+
+    await expect(provider.injectMessage("session-1", "barge in")).resolves.toEqual({
+      accepted: true,
+      messageId: "message-2",
+    });
+
+    await provider.pauseSession("session-1");
+    await provider.resumeSession("session-1");
+    await provider.killSession("session-1", false);
+
+    expect(httpService.axiosRef.post).toHaveBeenNthCalledWith(
+      1,
+      "https://gateway.example.com/api/sessions/session-1/inject",
+      { content: "barge in" },
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+      }
+    );
+    expect(httpService.axiosRef.post).toHaveBeenNthCalledWith(
+      2,
+      "https://gateway.example.com/api/sessions/session-1/pause",
+      {},
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+      }
+    );
+    expect(httpService.axiosRef.post).toHaveBeenNthCalledWith(
+      3,
+      "https://gateway.example.com/api/sessions/session-1/resume",
+      {},
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+      }
+    );
+    expect(httpService.axiosRef.post).toHaveBeenNthCalledWith(
+      4,
+      "https://gateway.example.com/api/sessions/session-1/kill",
+      { force: false },
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+        },
+      }
+    );
+  });
+
+  it("parses SSE stream messages", async () => {
+    const stream = Readable.from([
+      'data: {"id":"message-stream","sessionId":"session-stream","role":"assistant","content":"stream hello","timestamp":"2026-03-07T16:00:00.000Z"}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    httpService.axiosRef.get.mockResolvedValue({
+      data: stream,
+    });
+
+    const messages: Array<unknown> = [];
+    for await (const message of provider.streamMessages("session-stream")) {
+      messages.push(message);
+    }
+
+    expect(httpService.axiosRef.get).toHaveBeenCalledWith(
+      "https://gateway.example.com/api/sessions/session-stream/stream",
+      {
+        headers: {
+          Authorization: "Bearer plain-token",
+          Accept: "text/event-stream",
+        },
+        responseType: "stream",
+      }
+    );
+
+    expect(messages).toEqual([
+      {
+        id: "message-stream",
+        sessionId: "session-stream",
+        role: "assistant",
+        content: "stream hello",
+        timestamp: new Date("2026-03-07T16:00:00.000Z"),
+      },
+    ]);
+  });
+
+  it("throws ServiceUnavailableException for request failures", async () => {
+    httpService.axiosRef.get.mockRejectedValue(new Error("gateway unreachable"));
+
+    await expect(provider.listSessions()).rejects.toBeInstanceOf(ServiceUnavailableException);
+  });
+
+  it("returns false from isAvailable when gateway check fails", async () => {
+    httpService.axiosRef.get.mockRejectedValue(new Error("gateway unreachable"));
+
+    await expect(provider.isAvailable()).resolves.toBe(false);
+  });
+});

apps/orchestrator/src/api/providers/openclaw/openclaw.provider.ts

@@ -0,0 +1,703 @@
+import { HttpService } from "@nestjs/axios";
+import { Injectable, ServiceUnavailableException } from "@nestjs/common";
+import type {
+  AgentMessage,
+  AgentMessageRole,
+  AgentSession,
+  AgentSessionList,
+  AgentSessionStatus,
+  IAgentProvider,
+  InjectResult,
+} from "@mosaic/shared";
+import type { AgentProviderConfig } from "@prisma/client";
+import { randomUUID } from "node:crypto";
+import { EncryptionService } from "../../../security/encryption.service";
+
+const DEFAULT_SESSION_LIMIT = 50;
+const DEFAULT_MESSAGE_LIMIT = 50;
+const MAX_MESSAGE_LIMIT = 200;
+const OPENCLAW_PROVIDER_TYPE = "openclaw";
+const API_TOKEN_KEYS = ["apiToken", "token", "bearerToken"] as const;
+const DISPLAY_NAME_KEYS = ["displayName", "label"] as const;
+
+type JsonRecord = Record<string, unknown>;
+type AsyncChunkStream = AsyncIterable<string | Uint8Array | Buffer>;
+
+interface HttpErrorWithResponse {
+  response?: {
+    status?: number;
+  };
+}
+
+@Injectable()
+export class OpenClawProvider implements IAgentProvider {
+  readonly providerId: string;
+  readonly providerType = OPENCLAW_PROVIDER_TYPE;
+  readonly displayName: string;
+
+  constructor(
+    private readonly config: AgentProviderConfig,
+    private readonly encryptionService: EncryptionService,
+    private readonly httpService: HttpService
+  ) {
+    this.providerId = this.config.name;
+    this.displayName = this.resolveDisplayName();
+  }
+
+  validateBaseUrl(): void {
+    void this.resolveBaseUrl();
+  }
+
+  validateToken(): void {
+    void this.resolveApiToken();
+  }
+
+  async listSessions(cursor?: string, limit = DEFAULT_SESSION_LIMIT): Promise<AgentSessionList> {
+    const safeLimit = this.normalizeLimit(limit, DEFAULT_SESSION_LIMIT);
+    const params: Record<string, number | string> = { limit: safeLimit };
+    if (typeof cursor === "string" && cursor.length > 0) {
+      params.cursor = cursor;
+    }
+
+    try {
+      const response = await this.httpService.axiosRef.get(this.buildUrl("/api/sessions"), {
+        headers: this.authHeaders(),
+        params,
+      });
+
+      const page = this.extractSessionPage(response.data);
+      const sessions = page.records
+        .map((record) => this.toAgentSession(record))
+        .filter((session): session is AgentSession => session !== null);
+
+      return {
+        sessions,
+        total: page.total ?? sessions.length,
+        ...(page.cursor !== undefined ? { cursor: page.cursor } : {}),
+      };
+    } catch (error) {
+      throw this.toServiceUnavailable("list sessions", error);
+    }
+  }
+
+  async getSession(sessionId: string): Promise<AgentSession | null> {
+    try {
+      const response = await this.httpService.axiosRef.get(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}`),
+        {
+          headers: this.authHeaders(),
+        }
+      );
+
+      const payload = this.unwrapContainer(response.data, ["session", "data"]);
+      return this.toAgentSession(payload);
+    } catch (error) {
+      if (this.getHttpStatus(error) === 404) {
+        return null;
+      }
+
+      throw this.toServiceUnavailable(`get session ${sessionId}`, error);
+    }
+  }
+
+  async getMessages(
+    sessionId: string,
+    limit = DEFAULT_MESSAGE_LIMIT,
+    before?: string
+  ): Promise<AgentMessage[]> {
+    const safeLimit = this.normalizeLimit(limit, DEFAULT_MESSAGE_LIMIT);
+    const params: Record<string, number | string> = {
+      sessionId,
+      limit: safeLimit,
+    };
+
+    if (typeof before === "string" && before.length > 0) {
+      params.before = before;
+    }
+
+    try {
+      const response = await this.httpService.axiosRef.get(this.buildUrl("/api/messages"), {
+        headers: this.authHeaders(),
+        params,
+      });
+
+      return this.extractMessageRecords(response.data)
+        .map((record) => this.toAgentMessage(record, sessionId))
+        .filter((message): message is AgentMessage => message !== null);
+    } catch (error) {
+      throw this.toServiceUnavailable(`get messages for session ${sessionId}`, error);
+    }
+  }
+
+  async injectMessage(sessionId: string, content: string): Promise<InjectResult> {
+    try {
+      const response = await this.httpService.axiosRef.post(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/inject`),
+        { content },
+        {
+          headers: this.authHeaders(),
+        }
+      );
+
+      const payload = this.isRecord(response.data) ? response.data : {};
+
+      return {
+        accepted: typeof payload.accepted === "boolean" ? payload.accepted : true,
+        ...(this.readString(payload.messageId) !== undefined
+          ? { messageId: this.readString(payload.messageId) }
+          : {}),
+      };
+    } catch (error) {
+      throw this.toServiceUnavailable(`inject message into session ${sessionId}`, error);
+    }
+  }
+
+  async pauseSession(sessionId: string): Promise<void> {
+    try {
+      await this.httpService.axiosRef.post(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/pause`),
+        {},
+        {
+          headers: this.authHeaders(),
+        }
+      );
+    } catch (error) {
+      throw this.toServiceUnavailable(`pause session ${sessionId}`, error);
+    }
+  }
+
+  async resumeSession(sessionId: string): Promise<void> {
+    try {
+      await this.httpService.axiosRef.post(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/resume`),
+        {},
+        {
+          headers: this.authHeaders(),
+        }
+      );
+    } catch (error) {
+      throw this.toServiceUnavailable(`resume session ${sessionId}`, error);
+    }
+  }
+
+  async killSession(sessionId: string, force = true): Promise<void> {
+    try {
+      await this.httpService.axiosRef.post(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/kill`),
+        { force },
+        {
+          headers: this.authHeaders(),
+        }
+      );
+    } catch (error) {
+      throw this.toServiceUnavailable(`kill session ${sessionId}`, error);
+    }
+  }
+
+  async *streamMessages(sessionId: string): AsyncIterable<AgentMessage> {
+    try {
+      const response = await this.httpService.axiosRef.get(
+        this.buildUrl(`/api/sessions/${encodeURIComponent(sessionId)}/stream`),
+        {
+          headers: this.authHeaders({
+            Accept: "text/event-stream",
+          }),
+          responseType: "stream",
+        }
+      );
+
+      const stream = this.asAsyncChunkStream(response.data);
+      if (!stream) {
+        throw new Error("OpenClaw stream response is not readable");
+      }
+
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let streamDone = false;
+
+      for await (const chunk of stream) {
+        const textChunk =
+          typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+        buffer += textChunk.replace(/\r\n/gu, "\n");
+
+        const events = buffer.split("\n\n");
+        buffer = events.pop() ?? "";
+
+        for (const event of events) {
+          const data = this.extractSseData(event);
+          if (data === null) {
+            continue;
+          }
+
+          if (data === "[DONE]") {
+            streamDone = true;
+            break;
+          }
+
+          const message = this.toAgentMessage(this.tryParseJson(data) ?? data, sessionId);
+          if (message !== null) {
+            yield message;
+          }
+        }
+
+        if (streamDone) {
+          break;
+        }
+      }
+
+      if (!streamDone && buffer.trim().length > 0) {
+        const data = this.extractSseData(buffer.trim());
+        if (data !== null && data !== "[DONE]") {
+          const message = this.toAgentMessage(this.tryParseJson(data) ?? data, sessionId);
+          if (message !== null) {
+            yield message;
+          }
+        }
+      }
+    } catch (error) {
+      throw this.toServiceUnavailable(`stream messages for session ${sessionId}`, error);
+    }
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      this.validateBaseUrl();
+      this.validateToken();
+
+      await this.httpService.axiosRef.get(this.buildUrl("/api/sessions"), {
+        headers: this.authHeaders(),
+        params: { limit: 1 },
+      });
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private extractSessionPage(payload: unknown): {
+    records: unknown[];
+    total?: number;
+    cursor?: string;
+  } {
+    if (Array.isArray(payload)) {
+      return {
+        records: payload,
+        total: payload.length,
+      };
+    }
+
+    if (!this.isRecord(payload)) {
+      return {
+        records: [],
+      };
+    }
+
+    let records: unknown[] = [];
+    if (Array.isArray(payload.sessions)) {
+      records = payload.sessions;
+    } else if (Array.isArray(payload.items)) {
+      records = payload.items;
+    } else if (Array.isArray(payload.data)) {
+      records = payload.data;
+    }
+
+    const total = typeof payload.total === "number" ? payload.total : undefined;
+    const cursor = this.readString(payload.cursor) ?? this.readString(payload.nextCursor);
+
+    return {
+      records,
+      total,
+      ...(cursor !== undefined ? { cursor } : {}),
+    };
+  }
+
+  private extractMessageRecords(payload: unknown): unknown[] {
+    if (Array.isArray(payload)) {
+      return payload;
+    }
+
+    if (!this.isRecord(payload)) {
+      return [];
+    }
+
+    if (Array.isArray(payload.messages)) {
+      return payload.messages;
+    }
+
+    if (Array.isArray(payload.items)) {
+      return payload.items;
+    }
+
+    if (Array.isArray(payload.data)) {
+      return payload.data;
+    }
+
+    return [];
+  }
+
+  private unwrapContainer(payload: unknown, keys: string[]): unknown {
+    if (!this.isRecord(payload)) {
+      return payload;
+    }
+
+    for (const key of keys) {
+      if (key in payload) {
+        return payload[key];
+      }
+    }
+
+    return payload;
+  }
+
+  private toAgentSession(record: unknown): AgentSession | null {
+    if (!this.isRecord(record)) {
+      return null;
+    }
+
+    const id =
+      this.readString(record.id) ??
+      this.readString(record.sessionId) ??
+      this.readString(record.key);
+    if (!id) {
+      return null;
+    }
+
+    const createdAt = this.parseDate(record.createdAt ?? record.spawnedAt ?? record.startedAt);
+    const updatedAt = this.parseDate(
+      record.updatedAt ?? record.completedAt ?? record.lastActivityAt ?? record.endedAt,
+      createdAt
+    );
+
+    const label =
+      this.readString(record.label) ??
+      this.readString(record.title) ??
+      this.readString(record.name) ??
+      undefined;
+
+    const parentSessionId = this.readString(record.parentSessionId) ?? undefined;
+    const metadata = this.toMetadata(record.metadata);
+
+    return {
+      id,
+      providerId: this.providerId,
+      providerType: this.providerType,
+      ...(label !== undefined ? { label } : {}),
+      status: this.toSessionStatus(this.readString(record.status)),
+      ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+      createdAt,
+      updatedAt,
+      ...(metadata !== undefined ? { metadata } : {}),
+    };
+  }
+
+  private toAgentMessage(value: unknown, fallbackSessionId?: string): AgentMessage | null {
+    if (typeof value === "string") {
+      const content = value.trim();
+      if (content.length === 0 || fallbackSessionId === undefined) {
+        return null;
+      }
+
+      return {
+        id: randomUUID(),
+        sessionId: fallbackSessionId,
+        role: "assistant",
+        content,
+        timestamp: new Date(),
+      };
+    }
+
+    let candidate: JsonRecord | null = null;
+
+    if (this.isRecord(value) && this.isRecord(value.message)) {
+      candidate = value.message;
+    } else if (this.isRecord(value)) {
+      candidate = value;
+    }
+
+    if (candidate === null) {
+      return null;
+    }
+
+    const sessionId = this.readString(candidate.sessionId) ?? fallbackSessionId;
+    if (!sessionId) {
+      return null;
+    }
+
+    const content = this.extractMessageContent(
+      candidate.content ?? candidate.text ?? candidate.message
+    );
+    if (content.length === 0) {
+      return null;
+    }
+
+    const metadata = this.toMetadata(candidate.metadata);
+
+    return {
+      id: this.readString(candidate.id) ?? this.readString(candidate.messageId) ?? randomUUID(),
+      sessionId,
+      role: this.toMessageRole(this.readString(candidate.role) ?? this.readString(candidate.type)),
+      content,
+      timestamp: this.parseDate(candidate.timestamp ?? candidate.createdAt),
+      ...(metadata !== undefined ? { metadata } : {}),
+    };
+  }
+
+  private extractMessageContent(content: unknown): string {
+    if (typeof content === "string") {
+      return content.trim();
+    }
+
+    if (Array.isArray(content)) {
+      const parts: string[] = [];
+
+      for (const part of content) {
+        if (typeof part === "string") {
+          const trimmed = part.trim();
+          if (trimmed.length > 0) {
+            parts.push(trimmed);
+          }
+          continue;
+        }
+
+        if (!this.isRecord(part)) {
+          continue;
+        }
+
+        const text = this.readString(part.text) ?? this.readString(part.content);
+        if (text !== undefined && text.trim().length > 0) {
+          parts.push(text.trim());
+        }
+      }
+
+      return parts.join("\n\n").trim();
+    }
+
+    if (this.isRecord(content)) {
+      const text = this.readString(content.text) ?? this.readString(content.content);
+      return text?.trim() ?? "";
+    }
+
+    return "";
+  }
+
+  private toSessionStatus(status?: string): AgentSessionStatus {
+    switch (status?.toLowerCase()) {
+      case "active":
+      case "running":
+        return "active";
+      case "paused":
+        return "paused";
+      case "completed":
+      case "done":
+      case "succeeded":
+        return "completed";
+      case "failed":
+      case "error":
+      case "killed":
+      case "terminated":
+      case "cancelled":
+        return "failed";
+      case "idle":
+      case "pending":
+      case "queued":
+      default:
+        return "idle";
+    }
+  }
+
+  private toMessageRole(role?: string): AgentMessageRole {
+    switch (role?.toLowerCase()) {
+      case "assistant":
+      case "agent":
+        return "assistant";
+      case "system":
+        return "system";
+      case "tool":
+        return "tool";
+      case "operator":
+      case "user":
+      default:
+        return "user";
+    }
+  }
+
+  private normalizeLimit(value: number, fallback: number): number {
+    const normalized = Number.isFinite(value) ? Math.trunc(value) : fallback;
+    if (normalized < 1) {
+      return 1;
+    }
+
+    return Math.min(normalized, MAX_MESSAGE_LIMIT);
+  }
+
+  private parseDate(value: unknown, fallback = new Date()): Date {
+    if (value instanceof Date) {
+      return value;
+    }
+
+    if (typeof value === "string" || typeof value === "number") {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) {
+        return parsed;
+      }
+    }
+
+    return fallback;
+  }
+
+  private toMetadata(value: unknown): Record<string, unknown> | undefined {
+    if (this.isRecord(value)) {
+      return value;
+    }
+
+    return undefined;
+  }
+
+  private resolveDisplayName(): string {
+    const credentials = this.readCredentials();
+
+    for (const key of DISPLAY_NAME_KEYS) {
+      const value = this.readString(credentials[key]);
+      if (value !== undefined) {
+        return value;
+      }
+    }
+
+    return this.config.name;
+  }
+
+  private resolveBaseUrl(): string {
+    const configRecord = this.config as unknown as JsonRecord;
+    const rawBaseUrl =
+      this.readString(this.config.gatewayUrl) ?? this.readString(configRecord.baseUrl);
+
+    if (rawBaseUrl === undefined) {
+      throw new Error(`OpenClaw provider ${this.providerId} is missing gateway URL`);
+    }
+
+    try {
+      const parsed = new URL(rawBaseUrl);
+      return parsed.toString().replace(/\/$/u, "");
+    } catch {
+      throw new Error(`OpenClaw provider ${this.providerId} has invalid gateway URL`);
+    }
+  }
+
+  private resolveApiToken(): string {
+    const configRecord = this.config as unknown as JsonRecord;
+    const credentials = this.readCredentials();
+
+    const rawToken =
+      this.readString(configRecord.apiToken) ??
+      this.readString(configRecord.token) ??
+      this.readString(configRecord.bearerToken) ??
+      this.findFirstString(credentials, API_TOKEN_KEYS);
+
+    if (rawToken === undefined) {
+      throw new Error(`OpenClaw provider ${this.providerId} is missing apiToken credentials`);
+    }
+
+    try {
+      return this.encryptionService.decryptIfNeeded(rawToken);
+    } catch (error) {
+      throw new Error(`Failed to decrypt API token: ${this.toErrorMessage(error)}`);
+    }
+  }
+
+  private readCredentials(): JsonRecord {
+    return this.isRecord(this.config.credentials) ? this.config.credentials : {};
+  }
+
+  private findFirstString(record: JsonRecord, keys: readonly string[]): string | undefined {
+    for (const key of keys) {
+      const value = this.readString(record[key]);
+      if (value !== undefined) {
+        return value;
+      }
+    }
+
+    return undefined;
+  }
+
+  private authHeaders(extraHeaders: Record<string, string> = {}): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.resolveApiToken()}`,
+      ...extraHeaders,
+    };
+  }
+
+  private buildUrl(path: string): string {
+    return new URL(path, `${this.resolveBaseUrl()}/`).toString();
+  }
+
+  private extractSseData(rawEvent: string): string | null {
+    const lines = rawEvent.split("\n");
+    const dataLines = lines
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trimStart());
+
+    if (dataLines.length > 0) {
+      return dataLines.join("\n").trim();
+    }
+
+    const trimmed = rawEvent.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      return trimmed;
+    }
+
+    return null;
+  }
+
+  private tryParseJson(value: string): unknown {
+    try {
+      return JSON.parse(value) as unknown;
+    } catch {
+      return null;
+    }
+  }
+
+  private asAsyncChunkStream(value: unknown): AsyncChunkStream | null {
+    if (value !== null && typeof value === "object" && Symbol.asyncIterator in value) {
+      return value as AsyncChunkStream;
+    }
+
+    return null;
+  }
+
+  private isRecord(value: unknown): value is JsonRecord {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  private readString(value: unknown): string | undefined {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  private getHttpStatus(error: unknown): number | undefined {
+    if (typeof error !== "object" || error === null || !("response" in error)) {
+      return undefined;
+    }
+
+    const response = (error as HttpErrorWithResponse).response;
+    return typeof response?.status === "number" ? response.status : undefined;
+  }
+
+  private toServiceUnavailable(operation: string, error: unknown): ServiceUnavailableException {
+    return new ServiceUnavailableException(
+      `OpenClaw provider ${this.providerId} failed to ${operation}: ${this.toErrorMessage(error)}`
+    );
+  }
+
+  private toErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return String(error);
+  }
+}

apps/orchestrator/src/api/providers/providers.module.spec.ts

@@ -0,0 +1,131 @@
+import { Logger } from "@nestjs/common";
+import type { AgentProviderConfig } from "@prisma/client";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PrismaService } from "../../prisma/prisma.service";
+import { AgentProviderRegistry } from "../agents/agent-provider.registry";
+import { OpenClawProviderFactory } from "./openclaw/openclaw.provider-factory";
+import { ProvidersModule } from "./providers.module";
+
+type MockOpenClawProvider = {
+  providerId: string;
+  validateBaseUrl: ReturnType<typeof vi.fn>;
+  validateToken: ReturnType<typeof vi.fn>;
+  isAvailable: ReturnType<typeof vi.fn>;
+};
+
+describe("ProvidersModule", () => {
+  let moduleRef: ProvidersModule;
+  let prisma: {
+    agentProviderConfig: {
+      findMany: ReturnType<typeof vi.fn>;
+    };
+  };
+  let registry: {
+    registerProvider: ReturnType<typeof vi.fn>;
+  };
+  let factory: {
+    createProvider: ReturnType<typeof vi.fn>;
+  };
+
+  const config: AgentProviderConfig = {
+    id: "cfg-openclaw-1",
+    workspaceId: "workspace-1",
+    name: "openclaw-home",
+    provider: "openclaw",
+    gatewayUrl: "https://gateway.example.com",
+    credentials: { apiToken: "enc:token-value" },
+    isActive: true,
+    createdAt: new Date("2026-03-07T15:00:00.000Z"),
+    updatedAt: new Date("2026-03-07T15:00:00.000Z"),
+  };
+
+  beforeEach(() => {
+    prisma = {
+      agentProviderConfig: {
+        findMany: vi.fn(),
+      },
+    };
+
+    registry = {
+      registerProvider: vi.fn(),
+    };
+
+    factory = {
+      createProvider: vi.fn(),
+    };
+
+    moduleRef = new ProvidersModule(
+      prisma as unknown as PrismaService,
+      registry as unknown as AgentProviderRegistry,
+      factory as unknown as OpenClawProviderFactory
+    );
+  });
+
+  it("registers reachable OpenClaw providers", async () => {
+    const provider: MockOpenClawProvider = {
+      providerId: "openclaw-home",
+      validateBaseUrl: vi.fn(),
+      validateToken: vi.fn(),
+      isAvailable: vi.fn().mockResolvedValue(true),
+    };
+
+    prisma.agentProviderConfig.findMany.mockResolvedValue([config]);
+    factory.createProvider.mockReturnValue(provider);
+
+    await moduleRef.onModuleInit();
+
+    expect(prisma.agentProviderConfig.findMany).toHaveBeenCalledWith({
+      where: {
+        provider: "openclaw",
+        isActive: true,
+      },
+      orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+    });
+    expect(factory.createProvider).toHaveBeenCalledWith(config);
+    expect(provider.validateBaseUrl).toHaveBeenCalledTimes(1);
+    expect(provider.validateToken).toHaveBeenCalledTimes(1);
+    expect(provider.isAvailable).toHaveBeenCalledTimes(1);
+    expect(registry.registerProvider).toHaveBeenCalledWith(provider);
+  });
+
+  it("skips provider registration when gateway is unreachable", async () => {
+    const warnSpy = vi.spyOn(Logger.prototype, "warn").mockImplementation(() => undefined);
+    const provider: MockOpenClawProvider = {
+      providerId: "openclaw-home",
+      validateBaseUrl: vi.fn(),
+      validateToken: vi.fn(),
+      isAvailable: vi.fn().mockResolvedValue(false),
+    };
+
+    prisma.agentProviderConfig.findMany.mockResolvedValue([config]);
+    factory.createProvider.mockReturnValue(provider);
+
+    await moduleRef.onModuleInit();
+
+    expect(registry.registerProvider).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Skipping OpenClaw provider openclaw-home")
+    );
+  });
+
+  it("skips provider registration when token decryption fails", async () => {
+    const errorSpy = vi.spyOn(Logger.prototype, "error").mockImplementation(() => undefined);
+    const provider: MockOpenClawProvider = {
+      providerId: "openclaw-home",
+      validateBaseUrl: vi.fn(),
+      validateToken: vi.fn().mockImplementation(() => {
+        throw new Error("Failed to decrypt API token");
+      }),
+      isAvailable: vi.fn().mockResolvedValue(true),
+    };
+
+    prisma.agentProviderConfig.findMany.mockResolvedValue([config]);
+    factory.createProvider.mockReturnValue(provider);
+
+    await moduleRef.onModuleInit();
+
+    expect(registry.registerProvider).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("token decryption failed"));
+    expect(provider.isAvailable).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,94 @@
+import { HttpModule } from "@nestjs/axios";
+import { Logger, Module, OnModuleInit } from "@nestjs/common";
+import type { AgentProviderConfig } from "@prisma/client";
+import { PrismaModule } from "../../prisma/prisma.module";
+import { PrismaService } from "../../prisma/prisma.service";
+import { EncryptionService } from "../../security/encryption.service";
+import { AgentProviderRegistry } from "../agents/agent-provider.registry";
+import { AgentsModule } from "../agents/agents.module";
+import { OpenClawProviderFactory } from "./openclaw/openclaw.provider-factory";
+
+const OPENCLAW_PROVIDER_TYPE = "openclaw";
+
+@Module({
+  imports: [
+    AgentsModule,
+    PrismaModule,
+    HttpModule.register({
+      timeout: 10000,
+      maxRedirects: 5,
+    }),
+  ],
+  providers: [EncryptionService, OpenClawProviderFactory],
+})
+export class ProvidersModule implements OnModuleInit {
+  private readonly logger = new Logger(ProvidersModule.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly registry: AgentProviderRegistry,
+    private readonly openClawProviderFactory: OpenClawProviderFactory
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    const configs = await this.prisma.agentProviderConfig.findMany({
+      where: {
+        provider: OPENCLAW_PROVIDER_TYPE,
+        isActive: true,
+      },
+      orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+    });
+
+    for (const config of configs) {
+      await this.registerProvider(config);
+    }
+  }
+
+  private async registerProvider(config: AgentProviderConfig): Promise<void> {
+    const provider = this.openClawProviderFactory.createProvider(config);
+
+    try {
+      provider.validateBaseUrl();
+    } catch (error) {
+      this.logger.warn(
+        `Skipping OpenClaw provider ${config.name}: invalid configuration (${this.toErrorMessage(error)})`
+      );
+      return;
+    }
+
+    try {
+      provider.validateToken();
+    } catch (error) {
+      this.logger.error(
+        `Skipping OpenClaw provider ${config.name}: token decryption failed (${this.toErrorMessage(error)})`
+      );
+      return;
+    }
+
+    try {
+      const available = await provider.isAvailable();
+      if (!available) {
+        this.logger.warn(
+          `Skipping OpenClaw provider ${config.name}: gateway ${config.gatewayUrl} is unreachable`
+        );
+        return;
+      }
+    } catch (error) {
+      this.logger.warn(
+        `Skipping OpenClaw provider ${config.name}: gateway ${config.gatewayUrl} is unreachable (${this.toErrorMessage(error)})`
+      );
+      return;
+    }
+
+    this.registry.registerProvider(provider);
+    this.logger.log(`Registered OpenClaw provider ${provider.providerId}`);
+  }
+
+  private toErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return String(error);
+  }
+}

apps/orchestrator/src/app.module.ts

@@ -4,7 +4,10 @@ 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 { ProvidersModule } from "./api/providers/providers.module";
 import { CoordinatorModule } from "./coordinator/coordinator.module";
 import { BudgetModule } from "./budget/budget.module";
 import { CIModule } from "./ci";
@@ -51,6 +54,9 @@ import { orchestratorConfig } from "./config/orchestrator.config";
     ]),
     HealthModule,
     AgentsModule,
+    AgentProvidersModule,
+    ProvidersModule,
+    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/security/encryption.service.ts

@@ -0,0 +1,85 @@
+import { Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { createDecipheriv, hkdfSync } from "node:crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const ENCRYPTED_PREFIX = "enc:";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const DERIVED_KEY_LENGTH = 32;
+const HKDF_SALT = "mosaic.crypto.v1";
+const HKDF_INFO = "mosaic-db-secret-encryption";
+
+@Injectable()
+export class EncryptionService {
+  private key: Buffer | null = null;
+
+  constructor(private readonly configService: ConfigService) {}
+
+  decryptIfNeeded(value: string): string {
+    if (!this.isEncrypted(value)) {
+      return value;
+    }
+
+    return this.decrypt(value);
+  }
+
+  decrypt(encrypted: string): string {
+    if (!this.isEncrypted(encrypted)) {
+      throw new Error("Value is not encrypted");
+    }
+
+    const payloadBase64 = encrypted.slice(ENCRYPTED_PREFIX.length);
+
+    try {
+      const payload = Buffer.from(payloadBase64, "base64");
+      if (payload.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+        throw new Error("Encrypted payload is too short");
+      }
+
+      const iv = payload.subarray(0, IV_LENGTH);
+      const authTag = payload.subarray(payload.length - AUTH_TAG_LENGTH);
+      const ciphertext = payload.subarray(IV_LENGTH, payload.length - AUTH_TAG_LENGTH);
+
+      const decipher = createDecipheriv(ALGORITHM, this.getOrCreateKey(), iv);
+      decipher.setAuthTag(authTag);
+
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    } catch {
+      throw new Error("Failed to decrypt value");
+    }
+  }
+
+  isEncrypted(value: string): boolean {
+    return value.startsWith(ENCRYPTED_PREFIX);
+  }
+
+  private getOrCreateKey(): Buffer {
+    if (this.key !== null) {
+      return this.key;
+    }
+
+    const secret = this.configService.get<string>("MOSAIC_SECRET_KEY");
+    if (!secret) {
+      throw new Error(
+        "orchestrator: MOSAIC_SECRET_KEY is required. Set it in your config or via MOSAIC_SECRET_KEY."
+      );
+    }
+
+    if (secret.length < 32) {
+      throw new Error("MOSAIC_SECRET_KEY must be at least 32 characters");
+    }
+
+    this.key = Buffer.from(
+      hkdfSync(
+        "sha256",
+        Buffer.from(secret, "utf8"),
+        Buffer.from(HKDF_SALT, "utf8"),
+        Buffer.from(HKDF_INFO, "utf8"),
+        DERIVED_KEY_LENGTH
+      )
+    );
+
+    return this.key;
+  }
+}

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: {

apps/web/Dockerfile

@@ -24,6 +24,9 @@ COPY packages/ui/package.json ./packages/ui/
 COPY packages/config/package.json ./packages/config/
 COPY apps/web/package.json ./apps/web/
 
+# Copy npm configuration for native binary architecture hints
+COPY .npmrc ./
+
 # Install dependencies (no cache mount — Kaniko builds are ephemeral in CI)
 RUN pnpm install --frozen-lockfile
 
@@ -38,6 +41,9 @@ COPY packages/ui/package.json ./packages/ui/
 COPY packages/config/package.json ./packages/config/
 COPY apps/web/package.json ./apps/web/
 
+# Copy npm configuration for native binary architecture hints
+COPY .npmrc ./
+
 # Install production dependencies only
 RUN pnpm install --frozen-lockfile --prod
 

apps/web/src/app/(authenticated)/kanban/page.test.tsx

@@ -132,7 +132,7 @@ describe("KanbanPage add task flow", (): void => {
     });
 
     // Click the "+ Add task" button in the To Do column
-    const addTaskButtons = screen.getAllByRole("button", { name: /\+ Add task/i });
+    const addTaskButtons = await screen.findAllByRole("button", { name: /\+ Add task/i });
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     await user.click(addTaskButtons[0]!); // First column is "To Do"
 
@@ -165,7 +165,7 @@ describe("KanbanPage add task flow", (): void => {
     });
 
     // Click the "+ Add task" button
-    const addTaskButtons = screen.getAllByRole("button", { name: /\+ Add task/i });
+    const addTaskButtons = await screen.findAllByRole("button", { name: /\+ Add task/i });
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     await user.click(addTaskButtons[0]!);
 

apps/web/src/app/(authenticated)/mission-control/page.tsx

@@ -0,0 +1,5 @@
+import { MissionControlLayout } from "@/components/mission-control/MissionControlLayout";
+
+export default function MissionControlPage(): React.JSX.Element {
+  return <MissionControlLayout />;
+}

apps/web/src/app/(authenticated)/settings/agent-providers/page.tsx

@@ -0,0 +1,528 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ChangeEvent,
+  type ReactElement,
+  type SyntheticEvent,
+} from "react";
+import { Pencil, Trash2 } from "lucide-react";
+import { FleetSettingsNav } from "@/components/settings/FleetSettingsNav";
+import {
+  createAgentProvider,
+  deleteAgentProvider,
+  fetchAgentProviders,
+  updateAgentProvider,
+  type AgentProviderConfig,
+  type CreateAgentProviderRequest,
+  type UpdateAgentProviderRequest,
+} from "@/lib/api/agent-providers";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+
+interface ProviderFormData {
+  name: string;
+  provider: "openclaw";
+  gatewayUrl: string;
+  apiToken: string;
+  isActive: boolean;
+}
+
+const NAME_PATTERN = /^[a-zA-Z0-9-]+$/;
+
+const INITIAL_FORM: ProviderFormData = {
+  name: "",
+  provider: "openclaw",
+  gatewayUrl: "",
+  apiToken: "",
+  isActive: true,
+};
+
+function getErrorMessage(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return fallback;
+}
+
+function isValidHttpsUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function formatCreatedDate(value: string): string {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return "Unknown";
+  }
+
+  return new Intl.DateTimeFormat(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  }).format(parsed);
+}
+
+function validateForm(form: ProviderFormData, isEditing: boolean): string | null {
+  const name = form.name.trim();
+  if (name.length === 0) {
+    return "Name is required.";
+  }
+
+  if (!NAME_PATTERN.test(name)) {
+    return "Name must contain only letters, numbers, and hyphens.";
+  }
+
+  const gatewayUrl = form.gatewayUrl.trim();
+  if (gatewayUrl.length === 0) {
+    return "Gateway URL is required.";
+  }
+
+  if (!isValidHttpsUrl(gatewayUrl)) {
+    return "Gateway URL must be a valid https:// URL.";
+  }
+
+  if (!isEditing && form.apiToken.trim().length === 0) {
+    return "API token is required when creating a provider.";
+  }
+
+  return null;
+}
+
+export default function AgentProvidersSettingsPage(): ReactElement {
+  const [providers, setProviders] = useState<AgentProviderConfig[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [isRefreshing, setIsRefreshing] = useState<boolean>(false);
+  const [error, setError] = useState<string | null>(null);
+  const [successMessage, setSuccessMessage] = useState<string | null>(null);
+
+  const [isDialogOpen, setIsDialogOpen] = useState<boolean>(false);
+  const [editingProvider, setEditingProvider] = useState<AgentProviderConfig | null>(null);
+  const [form, setForm] = useState<ProviderFormData>(INITIAL_FORM);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [isSaving, setIsSaving] = useState<boolean>(false);
+
+  const [deleteTarget, setDeleteTarget] = useState<AgentProviderConfig | null>(null);
+  const [isDeleting, setIsDeleting] = useState<boolean>(false);
+
+  const loadProviders = useCallback(async (showLoadingState: boolean): Promise<void> => {
+    if (showLoadingState) {
+      setIsLoading(true);
+    } else {
+      setIsRefreshing(true);
+    }
+
+    try {
+      const data = await fetchAgentProviders();
+      setProviders(data);
+      setError(null);
+    } catch (loadError: unknown) {
+      setError(getErrorMessage(loadError, "Failed to load agent providers."));
+    } finally {
+      setIsLoading(false);
+      setIsRefreshing(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadProviders(true);
+  }, [loadProviders]);
+
+  function openCreateDialog(): void {
+    setEditingProvider(null);
+    setForm(INITIAL_FORM);
+    setFormError(null);
+    setIsDialogOpen(true);
+  }
+
+  function openEditDialog(provider: AgentProviderConfig): void {
+    setEditingProvider(provider);
+    setForm({
+      name: provider.name,
+      provider: "openclaw",
+      gatewayUrl: provider.gatewayUrl,
+      apiToken: "",
+      isActive: provider.isActive,
+    });
+    setFormError(null);
+    setIsDialogOpen(true);
+  }
+
+  function closeDialog(): void {
+    if (isSaving) {
+      return;
+    }
+
+    setIsDialogOpen(false);
+    setEditingProvider(null);
+    setForm(INITIAL_FORM);
+    setFormError(null);
+  }
+
+  async function handleSubmit(event: SyntheticEvent): Promise<void> {
+    event.preventDefault();
+    setFormError(null);
+    setSuccessMessage(null);
+
+    const validationError = validateForm(form, editingProvider !== null);
+    if (validationError !== null) {
+      setFormError(validationError);
+      return;
+    }
+
+    const name = form.name.trim();
+    const gatewayUrl = form.gatewayUrl.trim();
+    const apiToken = form.apiToken.trim();
+
+    try {
+      setIsSaving(true);
+
+      if (editingProvider) {
+        const updatePayload: UpdateAgentProviderRequest = {
+          name,
+          provider: form.provider,
+          gatewayUrl,
+          isActive: form.isActive,
+        };
+
+        if (apiToken.length > 0) {
+          updatePayload.credentials = { apiToken };
+        }
+
+        await updateAgentProvider(editingProvider.id, updatePayload);
+        setSuccessMessage(`Updated provider "${name}".`);
+      } else {
+        const createPayload: CreateAgentProviderRequest = {
+          name,
+          provider: form.provider,
+          gatewayUrl,
+          credentials: { apiToken },
+          isActive: form.isActive,
+        };
+
+        await createAgentProvider(createPayload);
+        setSuccessMessage(`Added provider "${name}".`);
+      }
+
+      setIsDialogOpen(false);
+      setEditingProvider(null);
+      setForm(INITIAL_FORM);
+      await loadProviders(false);
+    } catch (saveError: unknown) {
+      setFormError(getErrorMessage(saveError, "Unable to save agent provider."));
+    } finally {
+      setIsSaving(false);
+    }
+  }
+
+  async function handleDeleteProvider(): Promise<void> {
+    if (!deleteTarget) {
+      return;
+    }
+
+    try {
+      setIsDeleting(true);
+      await deleteAgentProvider(deleteTarget.id);
+      setSuccessMessage(`Deleted provider "${deleteTarget.name}".`);
+      setDeleteTarget(null);
+      await loadProviders(false);
+    } catch (deleteError: unknown) {
+      setError(getErrorMessage(deleteError, "Failed to delete agent provider."));
+    } finally {
+      setIsDeleting(false);
+    }
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto p-6 space-y-6">
+      <div className="space-y-4">
+        <div>
+          <h1 className="text-3xl font-bold">Agent Providers</h1>
+          <p className="text-muted-foreground mt-1">
+            Register OpenClaw gateways and API tokens used for external agent sessions.
+          </p>
+        </div>
+        <FleetSettingsNav />
+      </div>
+
+      <Card>
+        <CardHeader className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div>
+            <CardTitle>OpenClaw Gateways</CardTitle>
+            <CardDescription>
+              Add one or more OpenClaw gateway endpoints and control which ones are active.
+            </CardDescription>
+          </div>
+          <div className="flex items-center gap-2">
+            <Button
+              variant="outline"
+              onClick={() => {
+                void loadProviders(false);
+              }}
+              disabled={isLoading || isRefreshing}
+            >
+              {isRefreshing ? "Refreshing..." : "Refresh"}
+            </Button>
+            <Button onClick={openCreateDialog}>Add Provider</Button>
+          </div>
+        </CardHeader>
+
+        <CardContent className="space-y-3">
+          {error ? (
+            <p className="text-sm text-destructive" role="alert">
+              {error}
+            </p>
+          ) : null}
+
+          {successMessage ? <p className="text-sm text-emerald-600">{successMessage}</p> : null}
+
+          {isLoading ? (
+            <p className="text-sm text-muted-foreground">Loading agent providers...</p>
+          ) : providers.length === 0 ? (
+            <p className="text-sm text-muted-foreground">
+              No agent providers configured yet. Add one to register an OpenClaw gateway.
+            </p>
+          ) : (
+            providers.map((provider) => (
+              <div
+                key={provider.id}
+                className="rounded-lg border p-4 flex flex-col gap-4 md:flex-row md:items-start md:justify-between"
+              >
+                <div className="space-y-2 min-w-0">
+                  <div className="flex items-center gap-2 flex-wrap">
+                    <p className="font-semibold truncate">{provider.name}</p>
+                    <Badge variant={provider.isActive ? "default" : "secondary"}>
+                      {provider.isActive ? "Active" : "Inactive"}
+                    </Badge>
+                    <Badge variant="outline">{provider.provider}</Badge>
+                  </div>
+                  <p className="text-sm text-muted-foreground break-all">
+                    Gateway URL: {provider.gatewayUrl}
+                  </p>
+                  <p className="text-sm text-muted-foreground">
+                    Created: {formatCreatedDate(provider.createdAt)}
+                  </p>
+                </div>
+
+                <div className="flex items-center gap-2">
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() => {
+                      openEditDialog(provider);
+                    }}
+                  >
+                    <Pencil className="h-4 w-4 mr-2" />
+                    Edit
+                  </Button>
+                  <Button
+                    variant="destructive"
+                    size="sm"
+                    onClick={() => {
+                      setDeleteTarget(provider);
+                    }}
+                  >
+                    <Trash2 className="h-4 w-4 mr-2" />
+                    Delete
+                  </Button>
+                </div>
+              </div>
+            ))
+          )}
+        </CardContent>
+      </Card>
+
+      <Dialog
+        open={isDialogOpen}
+        onOpenChange={(nextOpen) => {
+          if (!nextOpen) {
+            closeDialog();
+            return;
+          }
+
+          setIsDialogOpen(true);
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>
+              {editingProvider ? "Edit Agent Provider" : "Add Agent Provider"}
+            </DialogTitle>
+            <DialogDescription>
+              Configure an OpenClaw gateway URL and API token for agent provider registration.
+            </DialogDescription>
+          </DialogHeader>
+
+          <form onSubmit={(event) => void handleSubmit(event)} className="space-y-4">
+            <div className="space-y-2">
+              <Label htmlFor="agent-provider-name">Name</Label>
+              <Input
+                id="agent-provider-name"
+                value={form.name}
+                onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                  setForm((previous) => ({ ...previous, name: event.target.value }));
+                }}
+                placeholder="openclaw-primary"
+                maxLength={100}
+                disabled={isSaving}
+                required
+              />
+              <p className="text-xs text-muted-foreground">
+                Use letters, numbers, and hyphens only.
+              </p>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="agent-provider-type">Provider Type</Label>
+              <Select
+                value={form.provider}
+                onValueChange={(value) => {
+                  if (value === "openclaw") {
+                    setForm((previous) => ({ ...previous, provider: value }));
+                  }
+                }}
+                disabled={isSaving}
+              >
+                <SelectTrigger id="agent-provider-type">
+                  <SelectValue placeholder="Select provider type" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="openclaw">openclaw</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="agent-provider-gateway-url">Gateway URL</Label>
+              <Input
+                id="agent-provider-gateway-url"
+                value={form.gatewayUrl}
+                onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                  setForm((previous) => ({ ...previous, gatewayUrl: event.target.value }));
+                }}
+                placeholder="https://my-openclaw.example.com"
+                disabled={isSaving}
+                required
+              />
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="agent-provider-api-token">API Token</Label>
+              <Input
+                id="agent-provider-api-token"
+                type="password"
+                value={form.apiToken}
+                onChange={(event: ChangeEvent<HTMLInputElement>) => {
+                  setForm((previous) => ({ ...previous, apiToken: event.target.value }));
+                }}
+                placeholder={
+                  editingProvider ? "Leave blank to keep existing token" : "Enter API token"
+                }
+                autoComplete="new-password"
+                disabled={isSaving}
+              />
+              <p className="text-xs text-muted-foreground">
+                {editingProvider
+                  ? "Leave blank to keep the currently stored token."
+                  : "Required when creating a provider."}
+              </p>
+            </div>
+
+            <div className="flex items-center justify-between rounded-md border px-3 py-2">
+              <div>
+                <Label htmlFor="agent-provider-active">Provider Status</Label>
+                <p className="text-xs text-muted-foreground">
+                  Inactive providers remain saved but are excluded from routing.
+                </p>
+              </div>
+              <Switch
+                id="agent-provider-active"
+                checked={form.isActive}
+                onCheckedChange={(checked) => {
+                  setForm((previous) => ({ ...previous, isActive: checked }));
+                }}
+                disabled={isSaving}
+              />
+            </div>
+
+            {formError ? (
+              <p className="text-sm text-destructive" role="alert">
+                {formError}
+              </p>
+            ) : null}
+
+            <DialogFooter>
+              <Button type="button" variant="outline" onClick={closeDialog} disabled={isSaving}>
+                Cancel
+              </Button>
+              <Button type="submit" disabled={isSaving}>
+                {isSaving ? "Saving..." : editingProvider ? "Save Changes" : "Create Provider"}
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+
+      <AlertDialog
+        open={deleteTarget !== null}
+        onOpenChange={(open) => {
+          if (!open && !isDeleting) {
+            setDeleteTarget(null);
+          }
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete Agent Provider</AlertDialogTitle>
+            <AlertDialogDescription>
+              Delete provider "{deleteTarget?.name}"? This permanently removes its gateway and token
+              configuration.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={isDeleting}>Cancel</AlertDialogCancel>
+            <AlertDialogAction onClick={handleDeleteProvider} disabled={isDeleting}>
+              {isDeleting ? "Deleting..." : "Delete Provider"}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}

apps/web/src/app/(authenticated)/settings/page.tsx

@@ -227,6 +227,33 @@ const categories: CategoryConfig[] = [
       </svg>
     ),
   },
+  {
+    title: "Agent Providers",
+    description:
+      "Register OpenClaw gateway URLs and API tokens for external agent provider routing.",
+    href: "/settings/agent-providers",
+    accent: "var(--ms-blue-400)",
+    iconBg: "rgba(47, 128, 255, 0.12)",
+    icon: (
+      <svg
+        width="20"
+        height="20"
+        viewBox="0 0 20 20"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path d="M4 6.5h12" />
+        <path d="M6.5 10h7" />
+        <path d="M4 13.5h12" />
+        <circle cx="5.5" cy="10" r="1.5" />
+        <circle cx="14.5" cy="10" r="1.5" />
+      </svg>
+    ),
+  },
   {
     title: "Agent Config",
     description: "Choose primary and fallback models, plus optional personality/SOUL instructions.",

apps/web/src/components/chat/AgentSelector.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import React from "react";
+
+interface AgentSelectorProps {
+  selectedAgent?: string | null;
+  onChange?: (agent: string | null) => void;
+  disabled?: boolean;
+}
+
+const AGENT_CONFIG = {
+  jarvis: {
+    displayName: "Jarvis",
+    role: "Orchestrator",
+    color: "#3498db",
+  },
+  builder: {
+    displayName: "Builder",
+    role: "Coding Agent",
+    color: "#3b82f6",
+  },
+  medic: {
+    displayName: "Medic",
+    role: "Health Monitor",
+    color: "#10b981",
+  },
+} as const;
+
+function JarvisIcon({ className }: { className?: string }): React.ReactElement {
+  return (
+    <svg
+      className={`w-3 h-3 ${className ?? ""}`}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <circle cx="12" cy="12" r="3" />
+      <path d="M12 2v4M12 22v-4" />
+      <path d="M2 12h4M22 12h-4" />
+    </svg>
+  );
+}
+
+function BuilderIcon({ className }: { className?: string }): React.ReactElement {
+  return (
+    <svg
+      className={`w-3 h-3 ${className ?? ""}`}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z" />
+    </svg>
+  );
+}
+
+function MedicIcon({ className }: { className?: string }): React.ReactElement {
+  return (
+    <svg
+      className={`w-3 h-3 ${className ?? ""}`}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <path d="M22 12h-4l-3 9L9 3l-3 9H2" />
+    </svg>
+  );
+}
+
+const AGENT_ICONS: Record<string, React.FC<{ className?: string }>> = {
+  jarvis: JarvisIcon,
+  builder: BuilderIcon,
+  medic: MedicIcon,
+};
+
+export function AgentSelector({
+  selectedAgent,
+  onChange,
+  disabled,
+}: AgentSelectorProps): React.ReactElement {
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-xs font-medium" style={{ color: "rgb(var(--text-muted))" }}>
+        Agent
+      </span>
+
+      <div className="flex flex-wrap gap-1">
+        {Object.entries(AGENT_CONFIG).map(([name, config]) => {
+          const Icon = AGENT_ICONS[name];
+          const isSelected = selectedAgent === name;
+
+          return (
+            <button
+              key={name}
+              type="button"
+              onClick={() => onChange?.(isSelected ? null : name)}
+              disabled={disabled}
+              className={`flex items-center gap-1.5 px-2 py-1.5 rounded-lg border transition-all text-xs ${
+                isSelected ? "border-primary bg-primary/10 shadow-sm" : "hover:bg-muted/50"
+              } ${disabled ? "opacity-50 cursor-not-allowed" : ""}`}
+              style={{
+                borderColor: isSelected
+                  ? "rgb(var(--accent-primary))"
+                  : "rgb(var(--border-default))",
+                color: isSelected ? "rgb(var(--accent-primary))" : "rgb(var(--text-primary))",
+              }}
+              title={`${config.displayName} — ${config.role}`}
+            >
+              <span
+                className="rounded-full"
+                style={{
+                  backgroundColor: config.color,
+                  width: "8px",
+                  height: "8px",
+                }}
+              />
+              {Icon && <Icon />}
+              <span className="font-medium">{config.displayName}</span>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

apps/web/src/components/chat/Chat.tsx

@@ -9,6 +9,7 @@ import { useWorkspaceId } from "@/lib/hooks";
 import { MessageList } from "./MessageList";
 import { ChatInput, type ModelId, DEFAULT_TEMPERATURE, DEFAULT_MAX_TOKENS } from "./ChatInput";
 import { ChatEmptyState } from "./ChatEmptyState";
+import { AgentSelector } from "./AgentSelector";
 import type { Message } from "@/hooks/useChat";
 
 export interface ChatRef {
@@ -66,6 +67,7 @@ export const Chat = forwardRef<ChatRef, ChatProps>(function Chat(
   const [selectedModel, setSelectedModel] = useState<ModelId>("llama3.2");
   const [temperature, setTemperature] = useState<number>(DEFAULT_TEMPERATURE);
   const [maxTokens, setMaxTokens] = useState<number>(DEFAULT_MAX_TOKENS);
+  const [selectedAgent, setSelectedAgent] = useState<string | null>(null);
 
   // Suggestion fill value: controls ChatInput's textarea content
   const [suggestionValue, setSuggestionValue] = useState<string | undefined>(undefined);
@@ -88,6 +90,7 @@ export const Chat = forwardRef<ChatRef, ChatProps>(function Chat(
     temperature,
     maxTokens,
     ...(initialProjectId !== undefined && { projectId: initialProjectId }),
+    ...(selectedAgent !== null && { agent: selectedAgent }),
   });
 
   // Read workspace ID from localStorage (set by auth-context after session check).
@@ -342,6 +345,31 @@ export const Chat = forwardRef<ChatRef, ChatProps>(function Chat(
       )}
 
       {/* Input Area */}
+      {!user && (
+        <div className="mx-4 mb-2 lg:mx-auto lg:max-w-4xl lg:px-8">
+          <div
+            className="flex items-center justify-center gap-2 rounded-lg border px-4 py-3 text-center"
+            style={{
+              backgroundColor: "rgb(var(--surface-1))",
+              borderColor: "rgb(var(--border-default))",
+            }}
+          >
+            <svg
+              className="h-4 w-4"
+              style={{ color: "rgb(var(--text-secondary))" }}
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              strokeWidth={2}
+            >
+              <path d="M15 7a2 2 0 012 2m4 0a6 6 0 01-7.743 5.743L11 17H9v2H7v2H4a1 1 0 01-1-1v-2.586a1 1 0 01.293-.707l5.964-5.964A6 6 0 1121 9z" />
+            </svg>
+            <span className="text-sm" style={{ color: "rgb(var(--text-secondary))" }}>
+              Sign in to chat with Jarvis
+            </span>
+          </div>
+        </div>
+      )}
       <div
         className="sticky bottom-0 border-t"
         style={{
@@ -350,6 +378,13 @@ export const Chat = forwardRef<ChatRef, ChatProps>(function Chat(
         }}
       >
         <div className="mx-auto max-w-4xl px-4 py-4 lg:px-8">
+          <div className="mb-3">
+            <AgentSelector
+              selectedAgent={selectedAgent}
+              onChange={setSelectedAgent}
+              disabled={isChatLoading || isStreaming || !user}
+            />
+          </div>
           <ChatInput
             onSend={handleSendMessage}
             disabled={isChatLoading || !user}

apps/web/src/components/chat/ChatOverlay.tsx

@@ -55,8 +55,8 @@ export function ChatOverlay(): React.JSX.Element {
         onClick={open}
         className="fixed bottom-6 right-6 z-50 flex h-14 w-14 items-center justify-center rounded-full shadow-lg transition-all hover:scale-110 focus:outline-none focus:ring-2 focus:ring-offset-2 lg:bottom-8 lg:right-8"
         style={{
-          backgroundColor: "rgb(var(--accent-primary))",
-          color: "rgb(var(--text-on-accent))",
+          backgroundColor: "var(--accent-primary, #10b981)",
+          color: "var(--text-on-accent, #ffffff)",
         }}
         aria-label="Open chat"
         title="Open Jarvis chat (Cmd+Shift+J)"
@@ -78,18 +78,18 @@ export function ChatOverlay(): React.JSX.Element {
   if (isMinimized) {
     return (
       <div
-        className="fixed bottom-0 right-0 z-40 w-full sm:w-96"
+        className="fixed bottom-0 right-0 z-40 w-full shadow-2xl sm:w-96"
         style={{
-          backgroundColor: "rgb(var(--surface-0))",
-          borderColor: "rgb(var(--border-default))",
+          backgroundColor: "var(--surface-0, #ffffff)",
+          borderColor: "var(--border-default, #e5e7eb)",
         }}
       >
         <button
           onClick={expand}
           className="flex w-full items-center justify-between border-t px-4 py-3 text-left transition-colors hover:bg-black/5 focus:outline-none focus:ring-2 focus:ring-inset"
           style={{
-            borderColor: "rgb(var(--border-default))",
-            backgroundColor: "rgb(var(--surface-0))",
+            borderColor: "var(--border-default, #e5e7eb)",
+            backgroundColor: "var(--surface-0, #ffffff)",
           }}
           aria-label="Expand chat"
         >
@@ -135,10 +135,10 @@ export function ChatOverlay(): React.JSX.Element {
 
       {/* Chat Panel */}
       <div
-        className="fixed inset-y-0 right-0 z-40 flex w-full flex-col border-l sm:w-96 lg:inset-y-16"
+        className="fixed inset-y-0 right-0 z-40 flex w-full flex-col border-l shadow-2xl sm:w-96 lg:inset-y-16"
         style={{
-          backgroundColor: "rgb(var(--surface-0))",
-          borderColor: "rgb(var(--border-default))",
+          backgroundColor: "var(--surface-0, #ffffff)",
+          borderColor: "var(--border-default, #e5e7eb)",
         }}
       >
         {/* Header */}

apps/web/src/components/layout/AppSidebar.tsx

@@ -156,6 +156,26 @@ function IconTerminal(): React.JSX.Element {
   );
 }
 
+function IconMissionControl(): React.JSX.Element {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="8" r="1.5" />
+      <path d="M11 5a4.25 4.25 0 0 1 0 6" />
+      <path d="M5 5a4.25 4.25 0 0 0 0 6" />
+      <path d="M13.5 2.5a7.75 7.75 0 0 1 0 11" />
+      <path d="M2.5 2.5a7.75 7.75 0 0 0 0 11" />
+    </svg>
+  );
+}
+
 function IconSettings(): React.JSX.Element {
   return (
     <svg
@@ -260,6 +280,11 @@ const NAV_GROUPS: NavGroup[] = [
         label: "Terminal",
         icon: <IconTerminal />,
       },
+      {
+        href: "/mission-control",
+        label: "Mission Control",
+        icon: <IconMissionControl />,
+      },
     ],
   },
   {

apps/web/src/components/mission-control/AuditLogDrawer.test.tsx

@@ -0,0 +1,205 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+
+interface MockButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  children: ReactNode;
+}
+
+interface MockBadgeProps extends HTMLAttributes<HTMLElement> {
+  children: ReactNode;
+}
+
+interface AuditLogEntry {
+  id: string;
+  userId: string;
+  sessionId: string;
+  provider: string;
+  action: string;
+  content: string | null;
+  metadata: unknown;
+  createdAt: string;
+}
+
+interface AuditLogResponse {
+  items: AuditLogEntry[];
+  total: number;
+  page: number;
+  pages: number;
+}
+
+const mockApiGet = vi.fn<(endpoint: string) => Promise<AuditLogResponse>>();
+
+vi.mock("@/lib/api/client", () => ({
+  apiGet: (endpoint: string): Promise<AuditLogResponse> => mockApiGet(endpoint),
+}));
+
+vi.mock("@/components/ui/button", () => ({
+  Button: ({ children, ...props }: MockButtonProps): React.JSX.Element => (
+    <button {...props}>{children}</button>
+  ),
+}));
+
+vi.mock("@/components/ui/badge", () => ({
+  Badge: ({ children, ...props }: MockBadgeProps): React.JSX.Element => (
+    <span {...props}>{children}</span>
+  ),
+}));
+
+import { AuditLogDrawer } from "./AuditLogDrawer";
+
+function renderWithQueryClient(ui: React.JSX.Element): ReturnType<typeof render> {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  });
+
+  return render(<QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>);
+}
+
+function responseWith(items: AuditLogEntry[], page: number, pages: number): AuditLogResponse {
+  return {
+    items,
+    total: items.length,
+    page,
+    pages,
+  };
+}
+
+describe("AuditLogDrawer", (): void => {
+  beforeEach((): void => {
+    vi.clearAllMocks();
+    mockApiGet.mockResolvedValue(responseWith([], 1, 0));
+  });
+
+  it("opens from trigger text and renders empty state", async (): Promise<void> => {
+    const user = userEvent.setup();
+
+    renderWithQueryClient(<AuditLogDrawer trigger="Audit" />);
+
+    await user.click(screen.getByRole("button", { name: "Audit" }));
+
+    await waitFor((): void => {
+      expect(screen.getByText("Audit Log")).toBeInTheDocument();
+      expect(screen.getByText("No audit entries found.")).toBeInTheDocument();
+    });
+  });
+
+  it("renders audit entries with action, session id, and payload", async (): Promise<void> => {
+    const user = userEvent.setup();
+
+    mockApiGet.mockResolvedValue(
+      responseWith(
+        [
+          {
+            id: "entry-1",
+            userId: "operator-1",
+            sessionId: "1234567890abcdef",
+            provider: "internal",
+            action: "inject",
+            content: "Run diagnostics",
+            metadata: { payload: { ignored: true } },
+            createdAt: "2026-03-07T19:00:00.000Z",
+          },
+        ],
+        1,
+        1
+      )
+    );
+
+    renderWithQueryClient(<AuditLogDrawer trigger="Audit" />);
+
+    await user.click(screen.getByRole("button", { name: "Audit" }));
+
+    await waitFor((): void => {
+      expect(screen.getByText("inject")).toBeInTheDocument();
+      expect(screen.getByText("12345678")).toBeInTheDocument();
+      expect(screen.getByText("Run diagnostics")).toBeInTheDocument();
+    });
+  });
+
+  it("supports pagination and metadata payload summary", async (): Promise<void> => {
+    const user = userEvent.setup();
+
+    mockApiGet.mockImplementation((endpoint: string): Promise<AuditLogResponse> => {
+      const query = endpoint.split("?")[1] ?? "";
+      const params = new URLSearchParams(query);
+      const page = Number(params.get("page") ?? "1");
+
+      if (page === 1) {
+        return Promise.resolve({
+          items: [
+            {
+              id: "entry-page-1",
+              userId: "operator-2",
+              sessionId: "abcdefgh12345678",
+              provider: "internal",
+              action: "pause",
+              content: "",
+              metadata: { payload: { reason: "hold" } },
+              createdAt: "2026-03-07T19:01:00.000Z",
+            },
+          ],
+          total: 2,
+          page: 1,
+          pages: 2,
+        });
+      }
+
+      return Promise.resolve({
+        items: [
+          {
+            id: "entry-page-2",
+            userId: "operator-3",
+            sessionId: "zzzz111122223333",
+            provider: "internal",
+            action: "kill",
+            content: null,
+            metadata: { payload: { force: true } },
+            createdAt: "2026-03-07T19:02:00.000Z",
+          },
+        ],
+        total: 2,
+        page: 2,
+        pages: 2,
+      });
+    });
+
+    renderWithQueryClient(<AuditLogDrawer trigger="Audit" />);
+
+    await user.click(screen.getByRole("button", { name: "Audit" }));
+
+    await waitFor((): void => {
+      expect(screen.getByText("Page 1 of 2")).toBeInTheDocument();
+      expect(screen.getByText("reason=hold")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+
+    await waitFor((): void => {
+      expect(screen.getByText("Page 2 of 2")).toBeInTheDocument();
+      expect(screen.getByText("force=true")).toBeInTheDocument();
+    });
+  });
+
+  it("includes sessionId filter in query string", async (): Promise<void> => {
+    const user = userEvent.setup();
+
+    renderWithQueryClient(<AuditLogDrawer trigger="Audit" sessionId="session 7" />);
+
+    await user.click(screen.getByRole("button", { name: "Audit" }));
+
+    await waitFor((): void => {
+      expect(mockApiGet).toHaveBeenCalled();
+    });
+
+    const firstCall = mockApiGet.mock.calls[0];
+    const endpoint = firstCall?.[0] ?? "";
+
+    expect(endpoint).toContain("sessionId=session+7");
+  });
+});