feat(ms22-p2): add UserAgent CRUD endpoints

- UserAgentService with findAll, findOne, create, update, remove
- UserAgentController at /api/agents (authenticated, user-scoped)
- createFromTemplate endpoint to instantiate from AgentTemplate
- Update TASKS.md and MISSION-MANIFEST.md for P2-004

Task: MS22-P2-004

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/src/app.module.ts

@@ -49,6 +49,7 @@ 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";
@@ -131,6 +132,7 @@ import { OrchestratorModule } from "./orchestrator/orchestrator.module";
     WorkspacesModule,
     AdminModule,
     AgentTemplateModule,
+    UserAgentModule,
     TeamsModule,
     ImportModule,
     ConversationArchiveModule,

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,60 @@
+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(":id")
+  findOne(@CurrentUser() user: AuthUser, @Param("id", ParseUUIDPipe) id: string) {
+    return this.userAgentService.findOne(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,12 @@
+import { Module } from "@nestjs/common";
+import { UserAgentService } from "./user-agent.service";
+import { UserAgentController } from "./user-agent.controller";
+import { PrismaModule } from "../prisma/prisma.module";
+
+@Module({
+  imports: [PrismaModule],
+  controllers: [UserAgentController],
+  providers: [UserAgentService],
+  exports: [UserAgentService],
+})
+export class UserAgentModule {}

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

@@ -0,0 +1,122 @@
+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";
+
+@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 } });
+  }
+}