feat(#93): implement agent spawn via federation

Implements FED-010: Agent Spawn via Federation feature that enables
spawning and managing Claude agents on remote federated Mosaic Stack
instances via COMMAND message type.

Features:
- Federation agent command types (spawn, status, kill)
- FederationAgentService for handling agent operations
- Integration with orchestrator's agent spawner/lifecycle services
- API endpoints for spawning, querying status, and killing agents
- Full command routing through federation COMMAND infrastructure
- Comprehensive test coverage (12/12 tests passing)

Architecture:
- Hub → Spoke: Spawn agents on remote instances
- Command flow: FederationController → FederationAgentService →
  CommandService → Remote Orchestrator
- Response handling: Remote orchestrator returns agent status/results
- Security: Connection validation, signature verification

Files created:
- apps/api/src/federation/types/federation-agent.types.ts
- apps/api/src/federation/federation-agent.service.ts
- apps/api/src/federation/federation-agent.service.spec.ts

Files modified:
- apps/api/src/federation/command.service.ts (agent command routing)
- apps/api/src/federation/federation.controller.ts (agent endpoints)
- apps/api/src/federation/federation.module.ts (service registration)
- apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint)
- apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration)

Testing:
- 12/12 tests passing for FederationAgentService
- All command service tests passing
- TypeScript compilation successful
- Linting passed

Refs #93

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

apps/api/src/federation/federation.controller.ts

@@ -8,10 +8,12 @@ import { Controller, Get, Post, UseGuards, Logger, Req, Body, Param, Query } fro
 import { FederationService } from "./federation.service";
 import { FederationAuditService } from "./audit.service";
 import { ConnectionService } from "./connection.service";
+import { FederationAgentService } from "./federation-agent.service";
 import { AuthGuard } from "../auth/guards/auth.guard";
 import { AdminGuard } from "../auth/guards/admin.guard";
 import type { PublicInstanceIdentity } from "./types/instance.types";
 import type { ConnectionDetails } from "./types/connection.types";
+import type { CommandMessageDetails } from "./types/message.types";
 import type { AuthenticatedRequest } from "../common/types/user.types";
 import {
   InitiateConnectionDto,
@@ -20,6 +22,7 @@ import {
   DisconnectConnectionDto,
   IncomingConnectionRequestDto,
 } from "./dto/connection.dto";
+import type { SpawnAgentCommandPayload } from "./types/federation-agent.types";
 import { FederationConnectionStatus } from "@prisma/client";
 
 @Controller("api/v1/federation")
@@ -29,7 +32,8 @@ export class FederationController {
   constructor(
     private readonly federationService: FederationService,
     private readonly auditService: FederationAuditService,
-    private readonly connectionService: ConnectionService
+    private readonly connectionService: ConnectionService,
+    private readonly federationAgentService: FederationAgentService
   ) {}
 
   /**
@@ -211,4 +215,81 @@ export class FederationController {
       connectionId: connection.id,
     };
   }
+
+  /**
+   * Spawn an agent on a remote federated instance
+   * Requires authentication
+   */
+  @Post("agents/spawn")
+  @UseGuards(AuthGuard)
+  async spawnAgentOnRemote(
+    @Req() req: AuthenticatedRequest,
+    @Body() body: { connectionId: string; payload: SpawnAgentCommandPayload }
+  ): Promise<CommandMessageDetails> {
+    if (!req.user?.workspaceId) {
+      throw new Error("Workspace ID not found in request");
+    }
+
+    this.logger.log(
+      `User ${req.user.id} spawning agent on remote instance via connection ${body.connectionId}`
+    );
+
+    return this.federationAgentService.spawnAgentOnRemote(
+      req.user.workspaceId,
+      body.connectionId,
+      body.payload
+    );
+  }
+
+  /**
+   * Get agent status from remote instance
+   * Requires authentication
+   */
+  @Get("agents/:agentId/status")
+  @UseGuards(AuthGuard)
+  async getAgentStatus(
+    @Req() req: AuthenticatedRequest,
+    @Param("agentId") agentId: string,
+    @Query("connectionId") connectionId: string
+  ): Promise<CommandMessageDetails> {
+    if (!req.user?.workspaceId) {
+      throw new Error("Workspace ID not found in request");
+    }
+
+    if (!connectionId) {
+      throw new Error("connectionId query parameter is required");
+    }
+
+    this.logger.log(
+      `User ${req.user.id} getting agent ${agentId} status via connection ${connectionId}`
+    );
+
+    return this.federationAgentService.getAgentStatus(req.user.workspaceId, connectionId, agentId);
+  }
+
+  /**
+   * Kill an agent on remote instance
+   * Requires authentication
+   */
+  @Post("agents/:agentId/kill")
+  @UseGuards(AuthGuard)
+  async killAgentOnRemote(
+    @Req() req: AuthenticatedRequest,
+    @Param("agentId") agentId: string,
+    @Body() body: { connectionId: string }
+  ): Promise<CommandMessageDetails> {
+    if (!req.user?.workspaceId) {
+      throw new Error("Workspace ID not found in request");
+    }
+
+    this.logger.log(
+      `User ${req.user.id} killing agent ${agentId} via connection ${body.connectionId}`
+    );
+
+    return this.federationAgentService.killAgentOnRemote(
+      req.user.workspaceId,
+      body.connectionId,
+      agentId
+    );
+  }
 }