feat(cli): command architecture — agents, missions, gateway-aware prdy (#158)

Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
2026-03-15 23:10:23 +00:00
parent 82c10a7b33
commit 4da255bf04
28 changed files with 1747 additions and 394 deletions
--- a/apps/gateway/src/tests/resource-ownership.test.ts
+++ b/apps/gateway/src/tests/resource-ownership.test.ts
@@ -1,4 +1,4 @@
-import { ForbiddenException } from '@nestjs/common';
+import { ForbiddenException, NotFoundException } from '@nestjs/common';
 import { describe, expect, it, vi } from 'vitest';
 import { ConversationsController } from '../conversations/conversations.controller.js';
 import { MissionsController } from '../missions/missions.controller.js';
@@ -25,12 +25,21 @@ function createBrain() {
    },
    missions: {
      findAll: vi.fn(),
+      findAllByUser: vi.fn(),
      findById: vi.fn(),
+      findByIdAndUser: vi.fn(),
      findByProject: vi.fn(),
      create: vi.fn(),
      update: vi.fn(),
      remove: vi.fn(),
    },
+    missionTasks: {
+      findByMissionAndUser: vi.fn(),
+      findByIdAndUser: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      remove: vi.fn(),
+    },
    tasks: {
      findAll: vi.fn(),
      findById: vi.fn(),
@@ -65,14 +74,14 @@ describe('Resource ownership checks', () => {
    );
  });

-  it('forbids access to a mission owned by another project owner', async () => {
+  it('forbids access to a mission owned by another user', async () => {
    const brain = createBrain();
-    brain.missions.findById.mockResolvedValue({ id: 'mission-1', projectId: 'project-1' });
-    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    // findByIdAndUser returns undefined when the mission doesn't belong to the user
+    brain.missions.findByIdAndUser.mockResolvedValue(undefined);
    const controller = new MissionsController(brain as never);

    await expect(controller.findOne('mission-1', { id: 'user-1' })).rejects.toBeInstanceOf(
-      ForbiddenException,
+      NotFoundException,
    );
  });

--- a/apps/gateway/src/agent/agent-config.dto.ts
+++ b/apps/gateway/src/agent/agent-config.dto.ts
@@ -0,0 +1,97 @@
+import {
+  IsArray,
+  IsBoolean,
+  IsIn,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+} from 'class-validator';
+
+const agentStatuses = ['idle', 'active', 'error', 'offline'] as const;
+
+export class CreateAgentConfigDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsString()
+  @MaxLength(255)
+  provider!: string;
+
+  @IsString()
+  @MaxLength(255)
+  model!: string;
+
+  @IsOptional()
+  @IsIn(agentStatuses)
+  status?: 'idle' | 'active' | 'error' | 'offline';
+
+  @IsOptional()
+  @IsUUID()
+  projectId?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50_000)
+  systemPrompt?: string;
+
+  @IsOptional()
+  @IsArray()
+  allowedTools?: string[];
+
+  @IsOptional()
+  @IsArray()
+  skills?: string[];
+
+  @IsOptional()
+  @IsBoolean()
+  isSystem?: boolean;
+
+  @IsOptional()
+  @IsObject()
+  config?: Record<string, unknown>;
+}
+
+export class UpdateAgentConfigDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  name?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  provider?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  model?: string;
+
+  @IsOptional()
+  @IsIn(agentStatuses)
+  status?: 'idle' | 'active' | 'error' | 'offline';
+
+  @IsOptional()
+  @IsUUID()
+  projectId?: string | null;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(50_000)
+  systemPrompt?: string | null;
+
+  @IsOptional()
+  @IsArray()
+  allowedTools?: string[] | null;
+
+  @IsOptional()
+  @IsArray()
+  skills?: string[] | null;
+
+  @IsOptional()
+  @IsObject()
+  config?: Record<string, unknown> | null;
+}
--- a/apps/gateway/src/agent/agent-configs.controller.ts
+++ b/apps/gateway/src/agent/agent-configs.controller.ts
@@ -0,0 +1,84 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  NotFoundException,
+  Param,
+  Patch,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import type { Brain } from '@mosaic/brain';
+import { BRAIN } from '../brain/brain.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { CreateAgentConfigDto, UpdateAgentConfigDto } from './agent-config.dto.js';
+
+@Controller('api/agents')
+@UseGuards(AuthGuard)
+export class AgentConfigsController {
+  constructor(@Inject(BRAIN) private readonly brain: Brain) {}
+
+  @Get()
+  async list(@CurrentUser() user: { id: string; role?: string }) {
+    return this.brain.agents.findAccessible(user.id);
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    const agent = await this.brain.agents.findById(id);
+    if (!agent) throw new NotFoundException('Agent not found');
+    if (!agent.isSystem && agent.ownerId !== user.id) {
+      throw new ForbiddenException('Agent does not belong to the current user');
+    }
+    return agent;
+  }
+
+  @Post()
+  async create(@Body() dto: CreateAgentConfigDto, @CurrentUser() user: { id: string }) {
+    return this.brain.agents.create({
+      ...dto,
+      ownerId: user.id,
+      isSystem: false,
+    });
+  }
+
+  @Patch(':id')
+  async update(
+    @Param('id') id: string,
+    @Body() dto: UpdateAgentConfigDto,
+    @CurrentUser() user: { id: string; role?: string },
+  ) {
+    const agent = await this.brain.agents.findById(id);
+    if (!agent) throw new NotFoundException('Agent not found');
+    if (agent.isSystem && user.role !== 'admin') {
+      throw new ForbiddenException('Only admins can update system agents');
+    }
+    if (!agent.isSystem && agent.ownerId !== user.id) {
+      throw new ForbiddenException('Agent does not belong to the current user');
+    }
+    const updated = await this.brain.agents.update(id, dto);
+    if (!updated) throw new NotFoundException('Agent not found');
+    return updated;
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async remove(@Param('id') id: string, @CurrentUser() user: { id: string; role?: string }) {
+    const agent = await this.brain.agents.findById(id);
+    if (!agent) throw new NotFoundException('Agent not found');
+    if (agent.isSystem) {
+      throw new ForbiddenException('Cannot delete system agents');
+    }
+    if (agent.ownerId !== user.id) {
+      throw new ForbiddenException('Agent does not belong to the current user');
+    }
+    const deleted = await this.brain.agents.remove(id);
+    if (!deleted) throw new NotFoundException('Agent not found');
+  }
+}
--- a/apps/gateway/src/agent/agent.module.ts
+++ b/apps/gateway/src/agent/agent.module.ts
@@ -5,6 +5,7 @@ import { RoutingService } from './routing.service.js';
 import { SkillLoaderService } from './skill-loader.service.js';
 import { ProvidersController } from './providers.controller.js';
 import { SessionsController } from './sessions.controller.js';
+import { AgentConfigsController } from './agent-configs.controller.js';
 import { CoordModule } from '../coord/coord.module.js';
 import { McpClientModule } from '../mcp-client/mcp-client.module.js';
 import { SkillsModule } from '../skills/skills.module.js';
@@ -13,7 +14,7 @@ import { SkillsModule } from '../skills/skills.module.js';
@Module({
  imports: [CoordModule, McpClientModule, SkillsModule],
  providers: [ProviderService, RoutingService, SkillLoaderService, AgentService],
-  controllers: [ProvidersController, SessionsController],
+  controllers: [ProvidersController, SessionsController, AgentConfigsController],
  exports: [AgentService, ProviderService, RoutingService, SkillLoaderService],
 })
 export class AgentModule {}
--- a/apps/gateway/src/agent/agent.service.ts
+++ b/apps/gateway/src/agent/agent.service.ts
@@ -49,6 +49,12 @@ export interface AgentSessionOptions {
  allowedTools?: string[];
  /** Whether the requesting user has admin privileges. Controls default tool access. */
  isAdmin?: boolean;
+  /**
+   * DB agent config ID. When provided, loads agent config from DB and merges
+   * provider, model, systemPrompt, and allowedTools. Explicit call-site options
+   * take precedence over config values.
+   */
+  agentConfigId?: string;
 }

 export interface AgentSession {
@@ -146,16 +152,39 @@ export class AgentService implements OnModuleDestroy {
    sessionId: string,
    options?: AgentSessionOptions,
  ): Promise<AgentSession> {
-    const model = this.resolveModel(options);
+    // Merge DB agent config when agentConfigId is provided
+    let mergedOptions = options;
+    if (options?.agentConfigId) {
+      const agentConfig = await this.brain.agents.findById(options.agentConfigId);
+      if (agentConfig) {
+        mergedOptions = {
+          provider: options.provider ?? agentConfig.provider,
+          modelId: options.modelId ?? agentConfig.model,
+          systemPrompt: options.systemPrompt ?? agentConfig.systemPrompt ?? undefined,
+          allowedTools: options.allowedTools ?? agentConfig.allowedTools ?? undefined,
+          sandboxDir: options.sandboxDir,
+          isAdmin: options.isAdmin,
+          agentConfigId: options.agentConfigId,
+        };
+        this.logger.log(
+          `Merged agent config "${agentConfig.name}" (${agentConfig.id}) into session ${sessionId}`,
+        );
+      }
+    }
+
+    const model = this.resolveModel(mergedOptions);
    const providerName = model?.provider ?? 'default';
    const modelId = model?.id ?? 'default';

    // Resolve sandbox directory: option > env var > process.cwd()
    const sandboxDir =
-      options?.sandboxDir ?? process.env['AGENT_FILE_SANDBOX_DIR'] ?? process.cwd();
+      mergedOptions?.sandboxDir ?? process.env['AGENT_FILE_SANDBOX_DIR'] ?? process.cwd();

    // Resolve allowed tool set
-    const allowedTools = this.resolveAllowedTools(options?.isAdmin ?? false, options?.allowedTools);
+    const allowedTools = this.resolveAllowedTools(
+      mergedOptions?.isAdmin ?? false,
+      mergedOptions?.allowedTools,
+    );

    this.logger.log(
      `Creating agent session: ${sessionId} (provider=${providerName}, model=${modelId}, sandbox=${sandboxDir}, tools=${allowedTools === null ? 'all' : allowedTools.join(',') || 'none'})`,
@@ -194,7 +223,8 @@ export class AgentService implements OnModuleDestroy {
    }

    // Build system prompt: platform prompt + skill additions appended
-    const platformPrompt = options?.systemPrompt ?? process.env['AGENT_SYSTEM_PROMPT'] ?? undefined;
+    const platformPrompt =
+      mergedOptions?.systemPrompt ?? process.env['AGENT_SYSTEM_PROMPT'] ?? undefined;
    const appendSystemPrompt =
      promptAdditions.length > 0 ? promptAdditions.join('\n\n') : undefined;

--- a/apps/gateway/src/chat/chat.dto.ts
+++ b/apps/gateway/src/chat/chat.dto.ts
@@ -28,4 +28,8 @@ export class ChatSocketMessageDto {
  @IsString()
  @MaxLength(255)
  modelId?: string;
+
+  @IsOptional()
+  @IsUUID()
+  agentId?: string;
 }
--- a/apps/gateway/src/chat/chat.gateway.ts
+++ b/apps/gateway/src/chat/chat.gateway.ts
@@ -83,6 +83,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
        agentSession = await this.agentService.createSession(conversationId, {
          provider: data.provider,
          modelId: data.modelId,
+          agentConfigId: data.agentId,
        });
      }
    } catch (err) {
--- a/apps/gateway/src/coord/coord.controller.ts
+++ b/apps/gateway/src/coord/coord.controller.ts
@@ -1,30 +1,17 @@
 import {
  BadRequestException,
-  Body,
  Controller,
-  Delete,
  Get,
-  HttpCode,
-  HttpStatus,
  Inject,
  NotFoundException,
  Param,
-  Patch,
-  Post,
  Query,
  UseGuards,
 } from '@nestjs/common';
 import fs from 'node:fs';
 import path from 'node:path';
 import { AuthGuard } from '../auth/auth.guard.js';
-import { CurrentUser } from '../auth/current-user.decorator.js';
 import { CoordService } from './coord.service.js';
-import type {
-  CreateDbMissionDto,
-  UpdateDbMissionDto,
-  CreateMissionTaskDto,
-  UpdateMissionTaskDto,
-} from './coord.dto.js';

 /** Walk up from cwd to find the monorepo root (has pnpm-workspace.yaml). */
 function findMonorepoRoot(start: string): string {
@@ -57,13 +44,15 @@ function resolveAndValidatePath(raw: string | undefined): string {
  return resolved;
 }

+/**
+ * File-based coord endpoints for agent tool consumption.
+ * DB-backed mission CRUD has moved to MissionsController at /api/missions.
+ */
@Controller('api/coord')
@UseGuards(AuthGuard)
 export class CoordController {
  constructor(@Inject(CoordService) private readonly coordService: CoordService) {}

-  // ── File-based coord endpoints (legacy) ──
-
  @Get('status')
  async missionStatus(@Query('projectPath') projectPath?: string) {
    const resolvedPath = resolveAndValidatePath(projectPath);
@@ -85,121 +74,4 @@ export class CoordController {
    if (!detail) throw new NotFoundException(`Task ${taskId} not found in coord mission`);
    return detail;
  }
-
-  // ── DB-backed mission endpoints ──
-
-  @Get('missions')
-  async listDbMissions(@CurrentUser() user: { id: string }) {
-    return this.coordService.getMissionsByUser(user.id);
-  }
-
-  @Get('missions/:id')
-  async getDbMission(@Param('id') id: string, @CurrentUser() user: { id: string }) {
-    const mission = await this.coordService.getMissionByIdAndUser(id, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    return mission;
-  }
-
-  @Post('missions')
-  async createDbMission(@Body() dto: CreateDbMissionDto, @CurrentUser() user: { id: string }) {
-    return this.coordService.createDbMission({
-      name: dto.name,
-      description: dto.description,
-      projectId: dto.projectId,
-      userId: user.id,
-      phase: dto.phase,
-      milestones: dto.milestones,
-      config: dto.config,
-      status: dto.status,
-    });
-  }
-
-  @Patch('missions/:id')
-  async updateDbMission(
-    @Param('id') id: string,
-    @Body() dto: UpdateDbMissionDto,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.updateDbMission(id, user.id, dto);
-    if (!mission) throw new NotFoundException('Mission not found');
-    return mission;
-  }
-
-  @Delete('missions/:id')
-  @HttpCode(HttpStatus.NO_CONTENT)
-  async deleteDbMission(@Param('id') id: string, @CurrentUser() user: { id: string }) {
-    const deleted = await this.coordService.deleteDbMission(id, user.id);
-    if (!deleted) throw new NotFoundException('Mission not found');
-  }
-
-  // ── DB-backed mission task endpoints ──
-
-  @Get('missions/:missionId/mission-tasks')
-  async listMissionTasks(
-    @Param('missionId') missionId: string,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.getMissionByIdAndUser(missionId, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    return this.coordService.getMissionTasksByMissionAndUser(missionId, user.id);
-  }
-
-  @Get('missions/:missionId/mission-tasks/:taskId')
-  async getMissionTask(
-    @Param('missionId') missionId: string,
-    @Param('taskId') taskId: string,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.getMissionByIdAndUser(missionId, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    const task = await this.coordService.getMissionTaskByIdAndUser(taskId, user.id);
-    if (!task) throw new NotFoundException('Mission task not found');
-    return task;
-  }
-
-  @Post('missions/:missionId/mission-tasks')
-  async createMissionTask(
-    @Param('missionId') missionId: string,
-    @Body() dto: CreateMissionTaskDto,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.getMissionByIdAndUser(missionId, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    return this.coordService.createMissionTask({
-      missionId,
-      taskId: dto.taskId,
-      userId: user.id,
-      status: dto.status,
-      description: dto.description,
-      notes: dto.notes,
-      pr: dto.pr,
-    });
-  }
-
-  @Patch('missions/:missionId/mission-tasks/:taskId')
-  async updateMissionTask(
-    @Param('missionId') missionId: string,
-    @Param('taskId') taskId: string,
-    @Body() dto: UpdateMissionTaskDto,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.getMissionByIdAndUser(missionId, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    const updated = await this.coordService.updateMissionTask(taskId, user.id, dto);
-    if (!updated) throw new NotFoundException('Mission task not found');
-    return updated;
-  }
-
-  @Delete('missions/:missionId/mission-tasks/:taskId')
-  @HttpCode(HttpStatus.NO_CONTENT)
-  async deleteMissionTask(
-    @Param('missionId') missionId: string,
-    @Param('taskId') taskId: string,
-    @CurrentUser() user: { id: string },
-  ) {
-    const mission = await this.coordService.getMissionByIdAndUser(missionId, user.id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    const deleted = await this.coordService.deleteMissionTask(taskId, user.id);
-    if (!deleted) throw new NotFoundException('Mission task not found');
-  }
 }
--- a/apps/gateway/src/coord/coord.service.ts
+++ b/apps/gateway/src/coord/coord.service.ts
@@ -1,6 +1,4 @@
-import { Injectable, Logger, Inject } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
-import { BRAIN } from '../brain/brain.tokens.js';
+import { Injectable, Logger } from '@nestjs/common';
 import {
  loadMission,
  getMissionStatus,
@@ -14,12 +12,14 @@ import {
 import { promises as fs } from 'node:fs';
 import path from 'node:path';

+/**
+ * File-based coord operations for agent tool consumption.
+ * DB-backed mission CRUD is handled directly by MissionsController via Brain repos.
+ */
@Injectable()
 export class CoordService {
  private readonly logger = new Logger(CoordService.name);

-  constructor(@Inject(BRAIN) private readonly brain: Brain) {}
-
  async loadMission(projectPath: string): Promise<Mission | null> {
    try {
      return await loadMission(projectPath);
@@ -74,68 +74,4 @@ export class CoordService {
      return [];
    }
  }
-
-  // ── DB-backed methods for multi-tenant mission management ──
-
-  async getMissionsByUser(userId: string) {
-    return this.brain.missions.findAllByUser(userId);
-  }
-
-  async getMissionByIdAndUser(id: string, userId: string) {
-    return this.brain.missions.findByIdAndUser(id, userId);
-  }
-
-  async getMissionsByProjectAndUser(projectId: string, userId: string) {
-    return this.brain.missions.findByProjectAndUser(projectId, userId);
-  }
-
-  async createDbMission(data: Parameters<Brain['missions']['create']>[0]) {
-    return this.brain.missions.create(data);
-  }
-
-  async updateDbMission(
-    id: string,
-    userId: string,
-    data: Parameters<Brain['missions']['update']>[1],
-  ) {
-    const existing = await this.brain.missions.findByIdAndUser(id, userId);
-    if (!existing) return null;
-    return this.brain.missions.update(id, data);
-  }
-
-  async deleteDbMission(id: string, userId: string) {
-    const existing = await this.brain.missions.findByIdAndUser(id, userId);
-    if (!existing) return false;
-    return this.brain.missions.remove(id);
-  }
-
-  // ── DB-backed methods for mission tasks (coord tracking) ──
-
-  async getMissionTasksByMissionAndUser(missionId: string, userId: string) {
-    return this.brain.missionTasks.findByMissionAndUser(missionId, userId);
-  }
-
-  async getMissionTaskByIdAndUser(id: string, userId: string) {
-    return this.brain.missionTasks.findByIdAndUser(id, userId);
-  }
-
-  async createMissionTask(data: Parameters<Brain['missionTasks']['create']>[0]) {
-    return this.brain.missionTasks.create(data);
-  }
-
-  async updateMissionTask(
-    id: string,
-    userId: string,
-    data: Parameters<Brain['missionTasks']['update']>[1],
-  ) {
-    const existing = await this.brain.missionTasks.findByIdAndUser(id, userId);
-    if (!existing) return null;
-    return this.brain.missionTasks.update(id, data);
-  }
-
-  async deleteMissionTask(id: string, userId: string) {
-    const existing = await this.brain.missionTasks.findByIdAndUser(id, userId);
-    if (!existing) return false;
-    return this.brain.missionTasks.remove(id);
-  }
 }
--- a/apps/gateway/src/missions/missions.controller.ts
+++ b/apps/gateway/src/missions/missions.controller.ts
@@ -2,7 +2,6 @@ import {
  Body,
  Controller,
  Delete,
-  ForbiddenException,
  Get,
  HttpCode,
  HttpStatus,
@@ -17,33 +16,42 @@ import type { Brain } from '@mosaic/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import { assertOwner } from '../auth/resource-ownership.js';
-import { CreateMissionDto, UpdateMissionDto } from './missions.dto.js';
+import {
+  CreateMissionDto,
+  UpdateMissionDto,
+  CreateMissionTaskDto,
+  UpdateMissionTaskDto,
+} from './missions.dto.js';

@Controller('api/missions')
@UseGuards(AuthGuard)
 export class MissionsController {
  constructor(@Inject(BRAIN) private readonly brain: Brain) {}

+  // ── Missions CRUD (user-scoped) ──
+
  @Get()
-  async list() {
-    return this.brain.missions.findAll();
+  async list(@CurrentUser() user: { id: string }) {
+    return this.brain.missions.findAllByUser(user.id);
  }

  @Get(':id')
  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
-    return this.getOwnedMission(id, user.id);
+    const mission = await this.brain.missions.findByIdAndUser(id, user.id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    return mission;
  }

  @Post()
  async create(@Body() dto: CreateMissionDto, @CurrentUser() user: { id: string }) {
-    if (dto.projectId) {
-      await this.getOwnedProject(dto.projectId, user.id, 'Mission');
-    }
    return this.brain.missions.create({
      name: dto.name,
      description: dto.description,
      projectId: dto.projectId,
+      userId: user.id,
+      phase: dto.phase,
+      milestones: dto.milestones,
+      config: dto.config,
      status: dto.status,
    });
  }
@@ -54,10 +62,8 @@ export class MissionsController {
    @Body() dto: UpdateMissionDto,
    @CurrentUser() user: { id: string },
  ) {
-    await this.getOwnedMission(id, user.id);
-    if (dto.projectId) {
-      await this.getOwnedProject(dto.projectId, user.id, 'Mission');
-    }
+    const existing = await this.brain.missions.findByIdAndUser(id, user.id);
+    if (!existing) throw new NotFoundException('Mission not found');
    const mission = await this.brain.missions.update(id, dto);
    if (!mission) throw new NotFoundException('Mission not found');
    return mission;
@@ -66,33 +72,81 @@ export class MissionsController {
  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)
  async remove(@Param('id') id: string, @CurrentUser() user: { id: string }) {
-    await this.getOwnedMission(id, user.id);
+    const existing = await this.brain.missions.findByIdAndUser(id, user.id);
+    if (!existing) throw new NotFoundException('Mission not found');
    const deleted = await this.brain.missions.remove(id);
    if (!deleted) throw new NotFoundException('Mission not found');
  }

-  private async getOwnedMission(id: string, userId: string) {
-    const mission = await this.brain.missions.findById(id);
+  // ── Mission Tasks sub-routes ──
+
+  @Get(':missionId/tasks')
+  async listTasks(@Param('missionId') missionId: string, @CurrentUser() user: { id: string }) {
+    const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
    if (!mission) throw new NotFoundException('Mission not found');
-    await this.getOwnedProject(mission.projectId, userId, 'Mission');
-    return mission;
+    return this.brain.missionTasks.findByMissionAndUser(missionId, user.id);
  }

-  private async getOwnedProject(
-    projectId: string | null | undefined,
-    userId: string,
-    resourceName: string,
+  @Get(':missionId/tasks/:taskId')
+  async getTask(
+    @Param('missionId') missionId: string,
+    @Param('taskId') taskId: string,
+    @CurrentUser() user: { id: string },
  ) {
-    if (!projectId) {
-      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
-    }
+    const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    const task = await this.brain.missionTasks.findByIdAndUser(taskId, user.id);
+    if (!task) throw new NotFoundException('Mission task not found');
+    return task;
+  }

-    const project = await this.brain.projects.findById(projectId);
-    if (!project) {
-      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
-    }
+  @Post(':missionId/tasks')
+  async createTask(
+    @Param('missionId') missionId: string,
+    @Body() dto: CreateMissionTaskDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    return this.brain.missionTasks.create({
+      missionId,
+      taskId: dto.taskId,
+      userId: user.id,
+      status: dto.status,
+      description: dto.description,
+      notes: dto.notes,
+      pr: dto.pr,
+    });
+  }

-    assertOwner(project.ownerId, userId, resourceName);
-    return project;
+  @Patch(':missionId/tasks/:taskId')
+  async updateTask(
+    @Param('missionId') missionId: string,
+    @Param('taskId') taskId: string,
+    @Body() dto: UpdateMissionTaskDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    const existing = await this.brain.missionTasks.findByIdAndUser(taskId, user.id);
+    if (!existing) throw new NotFoundException('Mission task not found');
+    const updated = await this.brain.missionTasks.update(taskId, dto);
+    if (!updated) throw new NotFoundException('Mission task not found');
+    return updated;
+  }
+
+  @Delete(':missionId/tasks/:taskId')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async removeTask(
+    @Param('missionId') missionId: string,
+    @Param('taskId') taskId: string,
+    @CurrentUser() user: { id: string },
+  ) {
+    const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    const existing = await this.brain.missionTasks.findByIdAndUser(taskId, user.id);
+    if (!existing) throw new NotFoundException('Mission task not found');
+    const deleted = await this.brain.missionTasks.remove(taskId);
+    if (!deleted) throw new NotFoundException('Mission task not found');
  }
 }
--- a/apps/gateway/src/missions/missions.dto.ts
+++ b/apps/gateway/src/missions/missions.dto.ts
@@ -1,6 +1,7 @@
-import { IsIn, IsObject, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+import { IsArray, IsIn, IsObject, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';

 const missionStatuses = ['planning', 'active', 'paused', 'completed', 'failed'] as const;
+const taskStatuses = ['not-started', 'in-progress', 'blocked', 'done', 'cancelled'] as const;

 export class CreateMissionDto {
  @IsString()
@@ -19,6 +20,19 @@ export class CreateMissionDto {
  @IsOptional()
  @IsIn(missionStatuses)
  status?: 'planning' | 'active' | 'paused' | 'completed' | 'failed';
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  phase?: string;
+
+  @IsOptional()
+  @IsArray()
+  milestones?: Record<string, unknown>[];
+
+  @IsOptional()
+  @IsObject()
+  config?: Record<string, unknown>;
 }

 export class UpdateMissionDto {
@@ -40,7 +54,70 @@ export class UpdateMissionDto {
  @IsIn(missionStatuses)
  status?: 'planning' | 'active' | 'paused' | 'completed' | 'failed';

+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  phase?: string;
+
+  @IsOptional()
+  @IsArray()
+  milestones?: Record<string, unknown>[];
+
+  @IsOptional()
+  @IsObject()
+  config?: Record<string, unknown>;
+
  @IsOptional()
  @IsObject()
  metadata?: Record<string, unknown> | null;
 }
+
+export class CreateMissionTaskDto {
+  @IsOptional()
+  @IsUUID()
+  taskId?: string;
+
+  @IsOptional()
+  @IsIn(taskStatuses)
+  status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  notes?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  pr?: string;
+}
+
+export class UpdateMissionTaskDto {
+  @IsOptional()
+  @IsUUID()
+  taskId?: string;
+
+  @IsOptional()
+  @IsIn(taskStatuses)
+  status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  notes?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  pr?: string;
+}